JSON over dashboards: what an agent-native SEO tool owes you

Most SEO tools are designed around a person looking at a screen. Charts, filters, saved views, a sidebar of features. That design is correct — for a person.

An agent is not a person. It does not scan a dashboard; it calls a command and parses a response. Building for it well means a different contract. These are the four terms we hold SEOCTL to.

1. One predictable shape per command

A human can absorb an inconsistent layout. An agent cannot. If volume sometimes returns {volume: 1900} and sometimes {search_volume: {value: 1900}}, every caller needs defensive parsing, and every agent prompt grows a paragraph of caveats.

So every SEOCTL command returns one flat, documented shape. volume always looks like a volume result. serp always looks like a serp result. The agent learns the shape once and trusts it forever.

2. Compact by default, trimmable on demand

Context is the agent’s working memory, and it is finite. A response with two hundred fields is not “thorough” — it is a tax on every token of reasoning that follows.

SEOCTL returns compact JSON with no pretty-printing unless you ask for it. List commands stream JSONL — one object per line — so a bulk run does not arrive as one enormous blob. And --fields lets the caller keep only the columns it needs:

seoctl serp "best crm software" --limit 10 --fields position,domain

That request answers “who ranks here” in ten short lines. No titles, no URLs, no snippets the agent did not ask for.

3. Atomic questions, atomic answers

A dashboard encourages exploration: load everything, then filter. An agent works the other way — it has a specific question and wants a specific answer.

SEOCTL commands map one-to-one onto questions. How much demand? volume. Who ranks? serp. Where does this domain sit? rank. What do competitors rank for? domain. There is no “pull the report and dig through it” step, because there is no report — just the answer.

4. Errors that are also data

When something fails, a dashboard shows a red banner. An agent cannot see a banner. If a failure is unstructured text, the agent either crashes or, worse, treats the error string as a result.

So a SEOCTL failure is still JSON. A bulk run that hits one bad row still emits one line for that row — a compact error object the caller can branch on. The agent can retry once with a smaller --limit, exactly as its agent instructions tell it to — and never silently switch country to force a result, because that would change the answer. The failure is something it can read.

The test we use

There is a simple test for whether a tool is genuinely built for agents: could an agent use it correctly with a paragraph of instructions and no trial and error?

A dashboard fails that test — it assumes eyes, a pointer, and a human’s tolerance for ambiguity. A tool that passes it has predictable shapes, small responses, atomic commands, and structured errors.

That test is why SEOCTL is a CLI that prints JSON, and not a web app with an API bolted on the side. The command line is not nostalgia. For an agent, it is the native interface — text in, text out, no surface area to misread.