SEOmatic

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds useful behavioral context beyond those annotations by explaining the tool is scoped to the connected workspace/site and that a domain parameter is only needed for competitor analysis. It does not contradict the annotations and gives the agent operational expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler: purpose and data types, usage guidance with a sibling alternative, then scoping/operational note. It is front-loaded with the most decision-relevant information and every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich annotations, complete parameter schema with detailed enum descriptions, and the existence of an output schema, the description covers everything an agent needs: purpose, when to use, which sibling to choose instead, and how the tool is scoped. There is no missing information that would prevent correct invocation or selection.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all five parameters, including the action enum and domain omission behavior. The description adds little parameter-level detail beyond reinforcing that domain is optional. Baseline 3 is appropriate because the schema, not the description, carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Read') and names the exact resource ('backlink profile of your own site or any competitor'), then lists concrete data types included: referring domains, anchor-text distribution, link velocity, and link-prospect intersects. It also distinguishes itself from serp_competitors by noting that tool is for rankings. This makes the tool's purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('for authority and link questions') and names the alternative for rankings ('use serp_competitors'). It also clarifies the default scope and that no domain parameter is needed unless analyzing a competitor. This is clear, actionable guidance with an explicit exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior. The description adds scoping context ('connected workspace and its site') and clarifies that no location parameter is required, which is useful beyond the annotations. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first covers purpose and capabilities, the second covers invocation context. No filler or redundant restatement of the tool's name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a complete input schema, an output schema, and safety annotations present, the description covers the remaining operational nuance: workspace/site scoping and direct invocation. Nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter and enum value explained in the schema. The description adds only the global 'no domain/site parameter' note and does not need to repeat per-parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description enumerates the exact operations ('list datasets, sample rows, list templates, and read one template') with a clear resource domain ('dataset library and page templates'). This is enough to distinguish it from SEO-focused siblings like keyword_research or site_pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly tells the agent to 'call directly' and that no domain/site parameter is needed because the tool is already scoped to the workspace. It doesn't name when-not-to-use alternatives, but the sibling tools are in a different domain, so exclusion is not critical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations by clarifying the tool is scoped to the connected workspace and site and that callers should not pass a domain/site parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first lists what the tool returns, the second gives usage context and names the alternative, and the third resolves a likely parameter question. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's multi-operation scope, the key decision of when to use it versus serp_competitors, and the scoping caveat about omitting domain/site parameters. With a full output schema, detailed parameter descriptions, and annotations, nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter and action value is already documented. The description itself adds little parameter-level meaning, though it does clarify that no domain/site parameter is required, which is useful. Baseline 3 is appropriate because the schema carries the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and object ('Research keyword demand') and enumerates the concrete outputs: search volume, difficulty, CPC, intent, keyword ideas, Trends interest, related queries, and Ads performance. It also explicitly distinguishes the tool from serp_competitors, so an agent can tell them apart immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly when to use this tool ('what to target and how much demand exists') and names the alternative for rankings ('who ranks today use serp_competitors'). It also gives a direct call instruction: no domain or site parameter is needed because it is already scoped.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds valuable context beyond annotations: the tool is scoped to the connected workspace/site, depends on what is connected, and requires no domain/site parameter. It also aligns with the readOnlyHint by describing a read operation. Minor additional details like pagination or empty-result behavior are not necessary because an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences: purpose, usage boundary, and scoping instruction. Every sentence contributes distinct information—there is no filler or repetition. The most decision-relevant information (what it reads and when to use it) appears first, and the call-direct guidance comes last but still earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 2-parameter read-only tool with an output schema, the description is complete. It covers what the tool does, when to use it versus a sibling, scope, and the fact that no domain/site parameter is needed. The caveat about connected actions is useful context, and nothing needed for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 even without extra parameter explanation. The description reinforces that 'keywords' are 'money keywords' and that the action is about local visibility, but it does not add new semantic detail beyond the schema's own descriptions. The enum on 'action' is self-documenting, and the optional 'keywords' array is already clearly explained in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Read'), a clear resource ('local search presence of the connected business'), and enumerates the concrete data covered: Business Profile locations, local ranking for money keywords, and review ratings. It also explicitly routes local/map-pack questions to this tool and national-ranking questions to a sibling, so it is readily distinguished from serp_competitors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is explicit: 'Use for local and map-pack questions; for national rankings use serp_competitors.' The description also tells the agent to call directly with no domain or site parameter, preventing a common unnecessary-parameter failure. This is actionable and leaves no ambiguity about when to invoke the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so safety is covered. The description adds useful behavioral context: the tool inspects the live landscape, is scoped to the connected workspace/site, and can be called directly without a domain parameter. It does not discuss rate limits or pagination, but the output schema and annotations lower that burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: main capability, sibling differentiation, and scoping instruction are each front-loaded and purposeful. The structure is dense but immediately scannable for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema, 100% parameter coverage, and annotations, the description covers what the tool does, when to use it, how it is scoped, and which sibling to choose instead. An agent has enough to select and invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter is already documented with conditional usage (e.g., domain omitted for own site, keywords for features only). The description provides a high-level summary but does not materially add meaning beyond the schema's parameter descriptions, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Inspect') and clearly defines the resource: live SERP features, domain rankings, visibility distribution, and competitor domains. It also differentiates from sibling keyword_research by stating the use case ('who ranks and why'), making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use for who ranks and why; for keyword demand use keyword_research,' naming the alternative and the condition that selects it. It also tells the agent that no domain/site parameter is needed because the tool is already scoped, removing a likely misuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful operational context about workspace scoping and the analyze/crawl modes, but does not disclose runtime behaviors such as pagination or limits; no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three efficient sentences with no wasted words. The action and outputs are front-loaded, followed by usage guidance and scoping context, each earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with a rich input schema, an output schema, and strong annotations, the description is complete. It covers what the tool does, when to use it, how it is scoped, and how to invoke it directly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the analyze/crawl distinction and clarifies that no domain/site parameter is needed, which helps slightly, but it does not add substantial meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Analyze') and names the concrete deliverables: on-page SEO score, critical issues, raw crawl metadata, and page inventory. It clearly positions the tool for page-level diagnosis and even names the alternative for search performance, so an agent can distinguish it without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides the intended use case ('page-level diagnosis') and points to gsc_performance for search-performance questions. It also tells the agent the tool is already scoped to the connected workspace, so no domain or site parameter is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.