budgetSEO

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

Adds behavior annotations don't cover: it spends 2 lookup credits and requires user confirmation before running. That is exactly the kind of cost/auth-adjacent detail the agent needs. It stops short of saying whether results are cached or what happens if the user declines.

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?

Four short, front-loaded sentences with no filler. The opening is a noun phrase rather than a verb phrase, which is slightly less scannable than a 'Returns X for Y' construction.

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?

Cost and batch-limit context is solid and an output schema exists so return values needn't be explained. The missing piece is differentiation from the keyword-lookup siblings, which is the main ambiguity an agent must resolve to select this tool.

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 coverage is 50%: countryCode is documented in the schema, keywords is not. The description's 'at most 20 keywords per call' merely restates the schema's maxItems: 20 and adds nothing about the string constraints (2–80 chars) or country defaults.

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 the resource (keywords the user names) and the exact outputs (volume, difficulty, intent), so an agent knows what it gets back. However, it never differentiates itself from siblings like lookup_keywords or research_keywords, which appear to operate on the same resource.

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?

Gives concrete operating guidance — confirm the 2-credit cost with the user first, cap at 20 keywords — but says nothing about when to choose this over lookup_keywords or research_keywords. Usage context is implied by the cost-confirmation rule rather than by explicit routing.

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?

The annotations already declare read-only, non-destructive, closed-world behavior, so the description need not cover safety. It adds useful scope by listing the opportunity categories and explaining kinds filtering, but it does not describe aggregation, ordering, or default behavior.

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 sentences, front-loaded with the primary use case and followed by the key filtering rule. There is no filler or repetition.

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 output schema and annotations cover return values and safety, and the description explains the main categories and kinds filter. However, it omits meaningful guidance on limit and projectId, leaving clear gaps for a three-parameter tool.

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 0%, so the description must compensate for all three parameters. It partially explains kinds by naming the opportunity categories, but it says nothing about limit or projectId.

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 clearly states a specific verb-like use case and resource: finding best opportunities across five named categories. It does not explicitly distinguish itself from sibling tools such as find_quick_wins or get_rank_changes, but the cross-category scope is understandable.

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 gives clear usage context: use this for best opportunities across the listed categories, and filter with kinds when the user names one. It lacks explicit when-not guidance or named alternatives, so it falls short of the top score.

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=true and destructiveHint=false, so safety is covered. The description adds that each result includes an estimated monthly clicks gain, which is genuine behavioral value, but says nothing about ordering, default limit, project scoping, or whether untracked keywords can appear. Adequate, not rich.

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 sentences, trigger condition first, return-value note second, zero padding. Nothing to cut.

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?

An output schema exists, so return structure needn't be explained, and the annotations cover the safety profile. What's missing is any treatment of the two undocumented parameters, which for a 0%-coverage schema is the main remaining gap.

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 0% for both parameters, so the description must compensate and it does not: neither limit nor projectId is mentioned. An agent cannot infer from the text whether projectId is optional (it is, since nothing is required) or what the cap of 25 means in practice.

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 names the concept the tool returns (low-hanging fruit / quick wins / striking-distance keywords) and adds that results carry estimated monthly clicks gained from moving up, which effectively defines the output. It stops short of one crisp verb+resource statement, but an agent can tell this apart from find_opportunities or get_keyword_action_plan.

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?

'Use when the user asks for low-hanging fruit, quick wins, or striking-distance keywords' gives explicit trigger language. There is no when-not guidance and no sibling alternative named for the case where the user wants broader opportunity data, so it falls short of a 5.

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 establish that this is a safe read-only, non-destructive, non-open-world operation. The description adds useful context about the kind of AI visibility data returned, but does not discuss freshness guarantees, limits, or other operational behavior beyond 'Latest'.

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 sentences with no wasted language. The data returned is stated first, followed immediately by the one parameter guidance.

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 simple one-parameter read-only tool with an output schema, the description covers the core purpose and projectId usage. It is nearly complete, though it could clarify default project behavior when projectId is omitted.

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 0%, so the description must explain projectId. It does so effectively by saying to pass projectId when the user has more than one project, clarifying both its purpose and optional nature, though it does not restate the UUID format already defined 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 clearly states the resource and scope: the latest AI search snapshot plus keywords where an AI Overview appears but does not cite the user. It is specific enough to distinguish this from general SEO and keyword tools, though it does not explicitly name sibling alternatives.

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 only usage guidance is about when to pass projectId, not when to use this tool versus siblings such as get_competitor_overview or get_seo_briefing. There are no exclusions or alternative-selection cues.

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?

Adds genuinely non-obvious behavior beyond the readOnly/openWorld annotations: it reads cached competitor data and will never trigger a paid lookup, and keywordsAhead may be null until a competitor is checked. Those are the two facts an agent needs to interpret sparse results correctly. It doesn't say what the ordering or result shape is, but the output schema covers returns.

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 short sentences with the core result front-loaded, then cost behavior, then the null caveat. Every sentence carries information an agent would otherwise have to guess.

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?

An output schema exists, so return shape needn't be explained, and the description still pre-explains the one field an agent would misread (keywordsAhead null). The only real omission is any reference to the projectId argument or to what a competitor entry contains, both partly mitigated by the schema.

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 0% and the description never mentions projectId, so it adds no semantic meaning about the one parameter. The parameter is a self-explanatory UUID named projectId, so the gap is minor, but nothing compensates for the missing schema description.

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 concrete verb+resource: returns competitors plus how many tracked keywords each outranks the user on. This is distinctive enough that an agent can distinguish it from siblings like find_opportunities or get_rank_changes. It stops short of naming an alternative, which keeps it at 4 rather than 5.

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 'uses saved competitor data only' clause implicitly tells the agent when this is the cheap/fast path, but there is no explicit when-to-use or when-to-prefer-another-tool guidance and no sibling is referenced. Usage is inferable rather than stated.

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=true and destructiveHint=false. The description adds the precondition that the calling agent must be able to edit the page, which is useful context, but 'Confirm with the user before changing the site' blurs the line — it describes a downstream write, not this read, and could leave an agent unsure whether the tool itself mutates anything.

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 short sentences, front-loaded with what the tool returns before the workflow caveat. The final warning sentence is slightly oblique relative to the read-only nature of the call, but it is not padding.

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?

An output schema exists, so return values need not be explained in detail, and the description still sketches them. For a one-parameter read tool with annotations, this is nearly sufficient; only the keywordId semantics and the read-vs-write ambiguity leave gaps.

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 coverage is 0% for the single keywordId (uuid) parameter, so the description carries the burden. 'One tracked keyword' implies a keyword identifier and that the keyword must already be tracked (via track_keywords), but it never explicitly ties that to the keywordId field or says what happens for an untracked keyword.

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?

Names a specific resource ('one tracked keyword') and enumerates the payload (ranking URL, history, SERP features, competitors, checklist), so an agent knows exactly what it gets. Differentiation from siblings is implied via 'after a briefing' (get_seo_briefing) but never stated outright.

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?

'Use after a briefing when an agent can edit the page' gives a clear sequencing precondition and a capability precondition. It does not name alternatives or say when NOT to call it, so it falls short of a full 5.

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 that this is read-only, non-destructive, and closed-world. The description adds useful context such as the default window, but does not explain the basis of comparison, data source, or other behavioral details beyond what annotations provide.

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 two short sentences, front-loads the core concept, and includes only useful additional information. Every sentence contributes to understanding.

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 simple read-only tool with an output schema and safety annotations, the description is adequate but incomplete. The unexplained `projectId` parameter and lack of differentiation from sibling tools leave gaps for an agent selecting and invoking 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 0%. The description explains that `days` defaults to 7, which is helpful, but it does not describe the `projectId` parameter at all or state the allowed range for `days`. It only partially compensates for the missing schema documentation.

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 clearly conveys that the tool reports winners and losers over a recent window, including what moved and what dropped. It does not explicitly name ranking or distinguish itself from sibling tools, but the core purpose is understandable.

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 gives explicit usage scenarios: inspecting what moved, what dropped, or conducting a weekly review. It does not mention when not to use it or name alternatives, but the intended context is clear.

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 and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: no lookup credits consumed, a fixed 28-day comparison window, and the critical guardrail that a false 'linked' value means the integration is not connected and clicks must not be fabricated.

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?

Four short sentences with zero filler, and the core metric list plus time window lead the text. The telegraphic phrasing ('Does not spend lookup credits') is slightly clipped but does not cost clarity.

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?

An output schema exists, so return structure needn't be explained, and annotations cover the safety profile. The description still supplies the freshness window, credit cost, and the linked=false behavior – the main things an agent needs to interpret and trust the response – though it could say more about what happens when the project isn't connected.

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?

There is one parameter with 0% schema description coverage – the schema only constrains projectId to a UUID. The description implies it identifies 'one project' but gives no guidance on where to obtain a valid projectId (e.g., via list_projects), so it only partially compensates for the gap.

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?

Names a specific verb (get) and resource (Google Search Console clicks, impressions, CTR, average position) scoped to one project, which is far more informative than the title alone. It does not explicitly contrast with siblings like get_rank_changes or get_competitor_overview, leaving some differentiation to inference.

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?

States the scope (one project, last 28 days plus previous 28 days) and notes that no lookup credits are spent, which implies 'call freely.' However, it never says when to prefer this over sibling tools such as get_rank_changes or get_seo_briefing, so the choice is left implicit.

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 readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds that the response includes plan limits and the next scheduled automatic check, hinting at background automation, but says nothing about how the two inputs affect behavior or whether project scoping changes results.

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 sentences, zero filler, front-loaded with the triggering situation followed by the payload. Every clause carries information an agent can act on.

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?

An output schema exists, so return values need no further explanation, and annotations cover the safety profile. The remaining gap is input semantics: an agent cannot tell what 'since' accepts or what omitting 'projectId' yields, which matters for a scoped briefing tool.

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 0% across two parameters, so the description carries the full burden and does not meet it. Neither 'since' (a bare string with no format stated) nor 'projectId' (a UUID) is explained, and 'recent'/'today' only vaguely gesture at a time window without defining it or noting that both params are optional.

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 names the resource (an SEO briefing/summary) and enumerates what it returns: top actions, recent rank moves, plan limits, next automatic check. 'Use this first' positions it as the entry-point aggregator, distinguishing it from narrower siblings like get_rank_changes or find_quick_wins, though it never explicitly contrasts with them.

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?

Trigger conditions are stated concretely: when the user asks what to do today, what changed, or what to focus on. The 'use this first' ordering is useful routing guidance. It stops short of 5 because no when-not condition or named alternative is given for follow-up drill-downs.

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=true and destructiveHint=false, so the safety profile is covered. The description adds a summary of what each result carries (counts, paused-by-plan flag, remaining slots), but says nothing about pagination, ordering, or whether all projects are returned — and the output schema already documents the return shape.

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?

A single front-loaded sentence with no filler; the verb and resource lead and the payload details follow.

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 an output schema present, the description needn't explain return values, and annotations cover safety; what remains is adequate. The only thin spot is the absence of usage context, which is minor for a zero-parameter read.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Schema coverage is 100% regardless.

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 and resource ("List the user's BudgetSEO projects") and even enumerates returned fields — keyword counts, plan-pause status, remaining slots. It clearly is the project-enumeration tool among keyword/domain-oriented siblings, though it never names a sibling to contrast with.

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?

No explicit when-to-use or when-not-to-use guidance, and no alternatives named. Its role as the natural entry point for discovering projects is implied only by the resource being "projects" versus the keyword/domain focus of every sibling.

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?

Discloses meaningful behavior beyond annotations: it costs 3 lookup credits unless cached, requires user confirmation, and includes a spamScore interpretation caveat. Annotations already cover openWorld and non-destructive behavior, and the output schema handles return structure, so remaining gaps are minor.

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 short sentences, front-loaded with what data is returned, followed immediately by cost and confirmation requirements. Every sentence carries actionable information, including the spamScore caveat.

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 one-parameter external lookup with an output schema and annotations covering openWorld and non-destructive behavior, the description covers the critical credit-confirmation constraint. The main remaining gap is that the domain input format is unspecified.

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?

The sole parameter, domain, has no schema description, and the tool description never specifies format, examples, or whether it accepts root domains versus full URLs. The parameter name is self-explanatory, but at 0% schema coverage the description does not compensate.

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?

Names the resource (backlinks) and enumerates the returned metrics: referring domains, backlink totals, and domain rank. The function is clear, but it does not explicitly contrast with the sibling lookup_domain tool.

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?

Provides a concrete prerequisite: tell the user the 3-credit cost and wait for confirmation before spending. It also warns not to treat spamScore as disavowal guidance. However, it does not state when to use this tool versus lookup_domain or when not to call it.

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?

Goes well beyond the annotations by disclosing a concrete cost (4 lookup credits), the caching exception that waives it, and a mandatory consent gate before spending. This also explains why readOnlyHint is false despite the operation being a read: it consumes account credits.

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?

Four short sentences, front-loaded with what the agent gets, then cost, then the consent requirement, then the default. Nothing is padded, though the opening noun phrase would read more clearly as a verb-led statement.

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?

An output schema exists so return values need no explanation, and the two non-obvious behaviors — credit cost and consent — are both covered. Minor gaps remain around cached vs fresh result differences and error behavior for malformed domains.

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 coverage is 50%; countryCode is already documented in the schema and the description merely restates its US default. The required `domain` parameter gets no added meaning — no guidance on bare domain vs URL, subdomain handling, or the minLength constraint — so the coverage gap is not compensated.

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?

Names the resource (a domain) and precisely enumerates the outputs: organic keywords, estimated traffic, top ranking URLs. That is enough to distinguish it from sibling lookups like lookup_backlinks and lookup_keywords, though the description never states the verb or explicitly contrasts with them.

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?

Gives a strong procedural rule — tell the user the 4-credit cost and wait for a yes — but says nothing about when to pick this over lookup_keywords, lookup_backlinks, or get_competitor_overview. Usage context is implied by the output list rather than stated.

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?

Adds substantial context beyond the annotations: a concrete credit cost, cache-avoidance of that cost, and a required human confirmation step before spending. The annotations only say it is a non-destructive, open-world operation; the description supplies the billing and consent behavior an agent must respect.

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?

Four very short sentences, front-loaded with what the tool returns, then cost, then the consent gate, then the sibling exclusion. No filler and nothing repeated from structured fields.

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?

An output schema exists, so return values need no prose, and the cost/consent model is covered. What is missing is anything about how caching is determined or how many ideas are returned per call, minor gaps given the schema and annotations already in place.

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 coverage is 50% — countryCode is documented in the schema while seed is not. The description clarifies cardinality ('from one seed'), which is genuine added meaning, but gives no length, format, or default guidance, so it sits at the baseline for a half-documented 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 concrete resource (keyword ideas from a single seed) and enumerates the returned metrics (volume, difficulty, intent), so an agent knows exactly what comes back. It also explicitly contrasts itself with the sibling research_keywords, removing ambiguity without opening either schema.

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?

Gives a real procedural rule — tell the user the 6-credit cost and wait for confirmation — and names the alternative (research_keywords). It does not state the condition under which research_keywords should be chosen instead, so the routing is only half-explicit.

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?

Goes well beyond the annotations by disclosing that the call consumes AI research usage (a billing cost), is plan-gated to Starter/Pro, requires a user confirmation step, and depends on prior audience setup. Annotations already flag it as non-read-only and open-world; the description adds the operational and cost context that matters most for a metered AI call, though it says nothing about runtime or whether existing keywords are affected.

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?

Four short sentences, each carrying distinct information: purpose, cost, plan eligibility, confirmation requirement, and prerequisite. Front-loaded with the action and free of filler.

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 an output schema present, return values need not be described, and the description covers cost, plan gating, confirmation, and the audience prerequisite. It could go slightly further on how the agent should discover a valid projectId or what happens if the audience 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 coverage is 0% for the single required projectId, so the description is the only prose source — but 'one project' only restates what the parameter name already implies. No format, sourcing (list_projects), or failure-mode guidance is given.

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 and resource ('Find new keyword ideas') scoped to 'one project', which distinguishes it from generic sibling tools. It does not explicitly contrast with nearby siblings like find_opportunities or find_quick_wins, so the agent must infer the boundary.

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?

Gives concrete usage conditions: confirm with the user first, available on Starter and Pro plans, and the project must have an audience configured in the SEO Agent. It stops short of naming an alternative tool for cases where those preconditions don't hold.

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 only declare that this is a non-destructive write; the description adds the resource consequence that matters here - it consumes plan keyword slots rather than lookup credits - plus a human-confirmation requirement. It doesn't say what happens to keywords already tracked or whether the slot consumption can be undone.

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 short sentences with the core action front-loaded and no filler. The confirmation sentence is placed after the cost note, which is a slightly odd ordering but still readable.

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 an output schema and annotations present, the description covers safety and credit impact well, but for a 4-parameter mutation with zero schema coverage it should at least state keyword count limits, batching, and whether existing tracked keywords are skipped or duplicated.

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 0%, so the description must carry parameter meaning, yet it only explains countryCode's default. projectId, device, and especially the keywords shape (single string vs array up to 500) are left entirely to the bare schema with no format or batching guidance.

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?

"Add keywords to a project" gives a specific verb plus resource, and the name/sibling pair (untrack_keyword) makes the direction of the operation obvious without opening the schema. It stops short of explicitly contrasting itself with research_keywords or untrack_keyword by name.

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 a real precondition ("Confirm the keywords with the user first") and a cost-based routing signal (uses plan keyword slots, not lookup credits), which implicitly separates it from research_keywords. It never names an alternative tool or says when not to use this one.

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 destructiveHint=true, so the description's job is to add specificity. It does: the deletion includes keyword history and is irreversible, plus an explicit human-confirmation requirement. It stops short of describing side effects on related reports or data retention.

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 short sentences, zero filler, with the destructive consequence and the confirmation requirement both front-loaded where the agent will see them.

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?

Output schema exists so return values need no explanation, and the mutation's risk profile and confirmation step are covered. The only real gap is how to source the required keywordId.

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 0% — keywordId is an undocumented UUID string with no hint where to obtain it. The description says 'one tracked keyword' but adds no format, source, or selection guidance, so the agent must infer how to get a valid id.

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 and resource ('Remove one tracked keyword') plus the scope of what goes with it ('and its history'). It is immediately distinguishable from the sibling track_keywords, being its inverse.

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?

Gives a clear procedural precondition: 'Confirm with the user before calling it.' It does not name an alternative action (e.g., re-tracking via track_keywords) or explain when untracking is preferable, but for a single-action destructive tool the given guidance is sufficient.

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 establish that this is a non-read-only, non-destructive, closed-world mutation. The description adds useful behavioral context beyond the annotations by explaining that marked actions will be skipped in later briefings and by clarifying the snooze date format.

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 short sentences with no filler and front-loads the core action. The extra detail about later briefings and snoozeUntil is directly useful and efficiently placed.

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 output schema and annotations reduce the description's burden, and it covers the downstream effect of the update. However, for a five-parameter mutation with no schema descriptions, it leaves essential identifiers such as projectId and actionKey unexplained.

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 0%, so the description must compensate for five undocumented parameters. It only explains the status values and the snoozeUntil date format; projectId, actionKey, and note receive no semantic explanation, and the status enum is already present 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 uses a specific verb (“Mark”) and resource (“briefing action”) and names the three target statuses. It clearly distinguishes a mutation from the sibling read/list tools, though it does not explicitly name the related briefing tool or use the tool name's “recommendation” terminology.

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 gives explicit timing: “Call this after the user finishes or rejects an action.” That is clear usage context for an agent, but it does not state when not to use the tool or mention alternative ways to handle briefing actions.

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