Promvia

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

Beyond annotations, it details return values (queryId, text, alreadyTracked, automaticChecksFrom), quota behavior, replacement transaction semantics, and specific refusal reasons. This is rich behavioral disclosure that an agent could not infer from the annotations alone.

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 first sentence is front-loaded and clear, but the description becomes a dense, run-on block with multiple parentheticals and repeated quota explanations. It is informative but lacks structure, and some details about automatic check scheduling could be tightened.

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 three parameters, no output schema, and the presence of annotations, the description is complete: it covers return values, replacement side effects, quota refusals, and edge cases like alreadyTracked. Nothing an agent needs to invoke the tool correctly 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 100%, so the schema already defines all three parameters. The description adds meaning for replacesQueryId by explaining the transactional replacement, quota slot behavior, and refusal conditions, which goes beyond the schema's simple 'archived, history kept' note.

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 resource: 'Track a new prompt on a site.' It distinguishes itself from archive_prompt and generate_brief by naming them as consumers of the returned queryId, and it clarifies that a prompt is never edited but replaced. This is a clear, sibling-aware purpose.

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 strong context: use replacesQueryId to replace instead of edit, and already-tracked prompts return alreadyTracked rather than creating a second row. It does not explicitly route the agent away from list_prompts or other siblings for discovery, but the when-not and alternative conditions are clearly 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?

Beyond the destructive/idempotent annotations, the description spells out the scope of destruction ('removes it and its future checks; history stays') so the agent knows historical data survives. It also documents the idempotent path ('alreadyArchived: true') and the failure path ('unknown-query') which archives nothing, so the caller can distinguish a refusal from a partial success.

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 dense sentences, front-loaded with the effect and its data-retention boundary, followed by the identifier source and the three possible outcomes. No filler, and the most consequential fact (history stays) is placed early.

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?

There is no output schema, and the description fully covers return values for the success, already-archived, and refused cases. Combined with the destructive scope statement and the id source, an agent has everything needed to invoke this correctly and interpret the result.

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%: siteId is documented in the schema but queryId has no schema description, and the description compensates by stating its provenance ('comes from list_prompts or add_prompt'). It does not describe the queryId format (opaque id vs. prompt text), which is the one remaining 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?

The description opens with a specific verb+resource ('Stop tracking a prompt') and immediately differentiates the operation from alternatives by naming where the identifier comes from ('queryId comes from list_prompts or add_prompt'). An agent can distinguish this from sibling listing/adding tools without reading the 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?

It gives clear context for use (cease tracking a prompt, which also stops future checks) and points to the two sibling tools that supply the required id. There is no explicit 'when not to use' or note about undoing an archive, but for a terminal operation with no sibling alternative the guidance is adequate.

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 destructiveHint=false, so safety is covered; the description goes beyond by disclosing the auth-dependent behavior (connected app reads the stored selection, API key always returns selected: null). It also hints at an accompanying sites list when no selection exists. The only soft spot is that the exact return shape is described informally rather than precisely.

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?

Front-loads the core question, then branches on the two deployment modes, then closes with the alternative tool — a clean three-move structure. No sentence is redundant and nothing is buried.

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 no output schema present, the description carries the burden of describing return values and does so: selected is null when nothing is chosen, the available sites are included, and API-key connections always yield null. Combined with the sibling routing, an agent has everything needed to call this correctly and interpret the result.

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 and the baseline is 4. The description correctly avoids inventing parameters and instead spends its words on return 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?

States a specific verb and resource — reporting the currently selected site for this connection — and frames it around the exact user question it answers ("which site am I on?"). It is clearly distinguishable from list_sites (enumerate choices) and select_site (mutate the selection), both named in the text.

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?

Names the intent that selects it, then explicitly redirects the alternative case: "To pick or change the site, call select_site with one from list_sites." Both the when and the when-not are present, with the correct sibling for each.

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 flag non-read-only, non-idempotent, destructive and open-world behavior; the description adds genuinely new context the annotations lack: plan entitlement and shared fair-use budget consumption. It could go further by saying the result is persisted/attached to the prompt and whether regeneration overwrites it.

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?

One sentence, front-loaded with the action and resource, with the constraints in parentheses. Nothing extraneous.

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?

No output schema exists, so the description should say more about what a 'brief' contains and whether the call is repeatable/billed each time. For a budget-consuming, destructive-flagged generation tool with an undocumented required parameter, this is adequate but with clear 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 50%: siteId is documented but queryId has no schema description. The phrase "for a tracked prompt" hints that queryId is a prompt identifier, but it never says where to get that id, leaving the required parameter's provenance implicit.

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?

Specific verb+resource: "Generate an AI content brief for a tracked prompt" tells the agent exactly what is produced and the scope (a single tracked prompt). It doesn't explicitly distinguish itself from similarly-named siblings like get_evidence or start_deep_scan, so it falls short of a 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?

Adds real gating information — Pro plan requirement and that it draws from the account's generation fair-use budget — which implies 'use sparingly.' However, it never states prerequisites such as obtaining queryId from list_prompts, nor when to prefer this over other evidence/scan tools.

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 say read-only/idempotent/closed-world; the description goes well beyond them by defining each availability reason ('scope', 'seat', 'disabled', 'plan'), noting that a viewer seat is read-only regardless of grant, that an API key is read-only by design, and that only the caller's own grant and account are described. This is exactly the context an agent needs to interpret the response and avoid pointless retries.

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?

It is front-loaded with the purpose, and nearly every clause carries real information, but the body is a single run-on sentence with nested parentheticals defining four failure reasons — accurate yet hard to parse at a glance. Splitting the availability reasons into a short list would keep the content while greatly improving scanability.

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?

There is no output schema, so the description must carry the return contract, and it does: every field is named and the enumerated reason values are defined. For a zero-parameter diagnostic tool, nothing an agent needs in order to call it or interpret its result 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?

There are zero parameters, so the baseline is 4; the description correctly implies a no-argument, caller-scoped call ('Only the caller's own grant and account are described'), which adds a small amount of meaning about implicit scoping.

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 opening clause states the exact resource and scope: 'What this connection can do right now', then enumerates the concrete fields returned (credential, plan, seat, scopes, siteAccess, per-tool availability). An agent can distinguish this diagnostic tool from siblings like get_usage or current_site without opening any 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?

Usage is only implied: the description explains what the availability flags mean, which suggests it is a pre-flight check before calling other tools, but it never states that explicitly, nor does it name a sibling alternative or an exclusion. The heavy explanation of failure reasons effectively does the routing work, so this is more than nothing but short of explicit guidance.

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/idempotent/non-destructive, so the bar is lower, yet the description adds a lot: hard bounds (max 90 days, max 100 rows per page), explicit pagination termination ('null on the last'), and the null-vs-empty distinction for observedQueries (null = engine does not expose searches, [] = none ran). It also discloses the caveat that movement across an instrument change may come from a model switch rather than the site, which is exactly the kind of interpretation guidance annotations cannot carry.

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?

Purpose, bounds, and pagination are front-loaded in the first two sentences, before the row-field detail. The single dense paragraph is efficient for the amount of information conveyed, though the long row-field enumeration would scan better broken into sentences or a list.

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?

There is no output schema, so the description carries the full burden of explaining return shape, and it does: scope lanes (full/daily/sweep), observedQueries, model with its temporal caveat, and instrumentChanges with its fields. For a bounded, paginated read-only list tool, an agent has everything needed to call it and interpret the result.

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 100%, so baseline is 3, but the description earns above baseline by resolving a naming mismatch: the schema's 'cursor' parameter is fed by the response's 'nextCursor'. It also restates the semantic meaning of the rows the days/engine filters select. It does not add anything for siteId, which the schema already covers thoroughly.

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 concrete verb+resource framing: 'Citation-check history for a site, newest first, filterable by engine and window.' It is unambiguous about what is returned and in what order. It stops short of naming how it differs from the sibling get_citations, so an agent must infer the history-vs-current distinction.

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 operational guidance for paging ('Pass nextCursor back as cursor ... to read the whole window'), which is genuinely useful. But there is no statement of when to call this versus get_citations or get_evidence, and no exclusions or prerequisites beyond the schema-stated siteId rules.

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/idempotent/non-destructive, but the description adds a great deal beyond them: null checkedAt means not measured yet, sentimentSource enumerates 'model'/'keyword'/null with the instruction to disclose keyword estimates, and shareOfVoiceSample carries counts, sample, a 95% Wilson interval, tooThin and earlyReading with a warning to always quote the sample. The demandBand caveat (a band, never a count, null on non-paid plans or when unmeasured) discloses plan-dependent behavior an agent could not infer from structured fields.

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?

Front-loads purpose and the buyer question before the field inventory, and with no output schema the field-by-field enumeration is largely earning its place. It is dense and long, with some near-restatement (sentiment/sentimentSource listed in the row then re-explained), but no filler sentences or marketing language.

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?

There is no output schema, so the description must carry the return contract, and it fully does: top-level fields, the per-prompt query row, the meaning of every ambiguous value, and the interpretation caveats on share-of-voice and demand. For a read-only single-parameter tool whose complexity lives in the response, an agent has everything needed to call it and to report results 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 coverage is 100% and the single siteId parameter already documents the connected-app-vs-API-key behavior and the select_site fallback. The description never mentions siteId or adds any scoping meaning beyond the schema, so the baseline 3 applies rather than a higher score for added meaning.

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?

Opens with a specific verb-and-resource statement plus scope: "The latest verdict for every tracked prompt on a site," and frames the agent question it answers. It then names the exact sibling tools (get_citation_history, get_evidence, get_sources_report) that cover adjacent needs, so the tool is distinguishable without opening any 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 explicit routing: use this for a current snapshot, use get_citation_history "for a window or a trend," get_evidence "for the answer text," and get_sources_report "for domains ranked across all prompts." It also defines the ambiguous word "latest" as each prompt's newest answers per engine rather than a time window, removing the most likely mis-invocation.

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 this a safe, idempotent, closed-world read, so the bar is lower; the description still adds genuine semantics about how the data is assembled (full crawl merged with newer diff overlays) and the notable behavior that robots-blocked pages are counted but never fetched. It stops short of describing the response shape or what happens when no scan 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?

One dense sentence, front-loaded with the resource and followed by the most decision-relevant qualifiers. Every clause (lifecycle, merge rule, robots handling) 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?

With no output schema, the description must describe the return value itself, and it does so only at a high level — 'lifecycle' and 'findings' are named but their fields, volume, or truncation behavior are not. For a read-only reporting tool it is adequate, but an agent cannot predict what it will actually receive.

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 a single parameter with 100% schema description coverage, including the connected-app vs API-key resolution rule, so the schema fully carries parameter meaning. The description adds nothing about siteId, which is acceptable at this coverage level but earns only the baseline.

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 a specific resource and its composition: latest run lifecycle plus merged page-level findings from the newest full crawl with newer diff overlays. That is concrete enough to distinguish it from generic metric tools, though it never states a verb or explicitly contrasts itself with siblings like get_geo_audit or get_evidence.

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?

There is no when-to-use guidance at all: no prerequisites, no conditions under which this beats get_geo_audit/get_evidence, and no indication of what to do if no scan has run yet. The agent must infer usage entirely from the name and the sibling list.

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 cover safety (readOnly, idempotent, closed-world, non-destructive), and the description adds context they cannot: only each prompt's latest answers, so result size scales with tracked prompts, plus the important semantic caveat that 'not exposed is never counted as none ran' for search-reporting engines. What it omits is any pagination or truncation guidance despite flagging unbounded growth, and it does not say what an empty result looks like.

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?

Front-loaded with purpose and alternatives before the field inventory, and every clause carries information. The long mid-sentence run of return fields is dense and would scan better as a list, but with no output schema that content is 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?

No output schema exists, so the description must carry the return shape itself — and it does, naming each field with meaning (position broken into rank/of/bucket with a null case, the own vs all vs domains citation split, observed searches with counts and per-engine exposure). Combined with the sibling routing and the latest-only scoping caveat, an agent has everything needed to call it correctly and interpret the result.

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 single siteId parameter is fully documented in the schema, including the connected-app vs API-key distinction and the constraint that a supplied id must match the selected site. The description adds nothing about siteId, so the schema does all the work; with 100% coverage that is the baseline 3.

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?

Opens with a specific framing — 'the raw answers behind get_citations' — then enumerates three concrete jobs (quote what an engine said, see which pages it cited, see what it searched for). That is a clear verb+resource statement that also differentiates it from the sibling that produces verdicts rather than raw evidence.

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 names when to use it and routes to three alternatives by condition: get_citation_history for earlier checks, get_citations for the per-prompt verdict and share of voice, get_sources_report for domains ranked across all prompts. Each alternative comes with the reason that selects it, leaving nothing to inference.

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, idempotent, closed-world and non-destructive, so the bar is lower; the description nonetheless adds real behavior: results are capped at 50 with totalActions and omitted indicating the true count, and consistency-check findings surface as technical items that clear only on a subsequent clean site check. It also flags that the paired update_action_status needs write access, which helps an agent plan around permission failures.

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?

Dense but front-loaded: the resource and its equivalence to the dashboard Fix list come first, followed by fields, truncation semantics and lifecycle. The long parenthetical clauses make it slightly heavy, but every clause carries information an agent needs.

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 no output schema, the description takes on the burden of describing return shape and does so: field list, status vocabulary, truncation fields, and how items get resolved. Nothing essential for correct invocation or interpretation appears 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?

The single siteId parameter is fully documented in the schema (100% coverage, including the connected-app vs API-key distinction), and the description adds nothing about it. Per the baseline rule for high schema coverage, 3 is appropriate.

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 concrete resource (the ranked GEO action plan, identical to the dashboard Fix list) and enumerates the fields returned (taskKey, title, kind, priority, effort, status), so an agent knows exactly what it gets. It stops short of naming which sibling it is not — get_opportunities and get_geo_audit are left for the agent to disambiguate.

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?

There is useful workflow context: taskKey is the handle that update_action_status consumes, and that tool requires write access. But there is no explicit when-to-use or when-not-to-use guidance versus siblings such as get_opportunities or get_geo_audit, so selection is only implied.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious semantics: the score is a weighted index rather than a proportion, carries no confidence interval and none should be inferred, and signals.consistency is excluded from the score. That prevents a whole class of interpretive errors an agent would otherwise make from the numbers alone.

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?

Purpose is front-loaded in the first clause, and the remaining detail earns its place because no output schema exists. The prose is somewhat dense and comma-spliced in the middle ('scoreBasis states that it carries no confidence interval, and none should be inferred'), but it is not padded.

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 no output schema, the description correctly spends its budget describing the return shape: score semantics, scoreBasis, and the consistency signal with its six rule checks and per-issue URLs/quotes. It does not mention other signals beyond consistency, nor behavior when no audit exists yet, which keeps it short of complete.

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 the single siteId parameter is fully documented there, including the connected-app vs API-key distinction, so the schema does the work. The description adds nothing about siteId, leaving the baseline of 3 appropriate.

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?

Opens with a specific verb+resource: 'Get a site's latest GEO readiness audit' plus what it returns (overall grade/score and findings to fix). This distinguishes it from score-only siblings like get_visibility_score or get_metrics, though it never explicitly contrasts with get_deep_scan or get_geo_actions, which are the nearest neighbors.

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 is only implied: 'the specific findings to fix' suggests calling it when the agent needs remediation guidance, and 'latest' implies no historical query. There is no explicit when-to-use statement, no exclusion, and no named alternative among the 17 siblings (e.g. get_deep_scan, get_geo_actions), so the agent must infer 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: exactly which figures are all-time versus a 30-day window, that aiVisits.likely is inferred rather than counted, and how sampling is reported (visitor counts plus a 95% Wilson interval, and deliberately no interval on visitorQualityLift because a ratio of rates is not a proportion). This is the kind of interpretation guidance that prevents analytic misuse.

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?

Content is front-loaded with the resource summary, and nearly every clause carries meaning, but the body is a dense semicolon-chained wall of field-level specification that is hard to scan. The sampling/z-test rationale is legitimately needed given no output schema, yet the lack of any structural breaks costs readability.

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 no output schema, the description carries the full burden of explaining return values, and it does name the key fields, their windows, and their sample structures. Remaining gaps are modest: no error behavior, no note on auth failures beyond the schema, and no mention of sibling reports that overlap in subject matter.

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 a single parameter at 100% schema description coverage, and the schema already spells out the connected-app versus API-key requirements and the select_site interaction. The description adds nothing about siteId, so it neither compensates nor detracts — 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?

The description opens with a specific resource definition — attributed visits, verified revenue by currency and source, unverified conversions kept separate — so an agent knows exactly what data comes back. It also anchors the tool to REST /v1/sites/{siteId}/metrics. It stops short of naming any sibling (e.g. get_sources_report, get_visibility_score) to differentiate scope, so it is clear but not sibling-routing.

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 is only implied: this is the metrics tool, and the guidance given is about consuming output ("Never add or divide figures from different windows"), not about when to pick this over another tool. No alternative tool is named and no precondition such as needing select_site first is stated here, even though the schema hints at 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: results are open candidates only, sorted highest score first, and when the feature is not enabled the list is empty with an explanatory note. The full score composition (40% visibility gap / 35% commercial intent / 25% rival citations, ±20% for search demand) is disclosed, which an agent cannot infer from 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?

Purpose and use case are front-loaded before the return-field inventory, and every sentence carries information. The score-weighting breakdown is dense and parenthetical but earns its space because there is no output schema; only minor tightening is possible.

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 no output schema, the description does the necessary work of enumerating returned fields, their types/domains, and the empty-result case. The one remaining gap is volume/limit behavior — how many candidates come back and whether the list can be truncated — which an agent planning around the result would want.

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 only one parameter and its schema description is fully covered (100%), so the schema carries the semantics of siteId, including the connected-app vs API-key distinction. The description adds no additional meaning about siteId beyond the implicit "a site's tracking" framing, 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?

Opens with a concrete verb+resource framing ("Questions worth adding to a site's tracking, best first") and explicitly separates itself from list_prompts (already tracked) and get_prompt_templates (country/language/persona variants). An agent can distinguish this from all 25 siblings without opening any 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 an explicit triggering question ("what should we track next?") and names the alternatives with the condition that selects each: list_prompts for what is tracked, get_prompt_templates for variants, add_prompt to actually track a candidate. It also states the prerequisite for the follow-up action (add_prompt needs write access).

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/idempotent/non-destructive, so the safety profile needs no restatement. The description adds genuinely new behavior: the empty-list-plus-note state when the feature is not enabled, and the queryId join key for splitting metrics in get_citations, get_evidence and get_citation_history. It does not discuss pagination or size limits for large template sets, which keeps it off a 5.

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 content is dense and useful, but the structure is poor: it opens with a sentence fragment ('How a site's tracked prompts are grouped into templates and variants:') and then runs long compound sentences chaining return fields and siblings together. The parenthetical join instruction is valuable but buried mid-stream rather than front-loaded or separated.

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 no output schema, the description carries the full burden and does: return envelope (site + templates), per-template fields, per-variant fields with null semantics, the join key to other tools, and the disabled-feature state. Nothing an agent needs to call it and interpret the response 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?

The single siteId parameter is fully documented in the schema (100% coverage), including the connected-app vs API-key distinction. The description adds no parameter-level meaning beyond that, so 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?

States precisely what is returned — site grouping of tracked prompts into templates and variants, with template id/text and per-variant dimensions — and explicitly distinguishes itself from list_prompts (every tracked prompt) and get_opportunities (untracked questions). An agent can tell what this resource is and isn't without opening any 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 the concrete use case (compare results by country, language, persona, funnel stage, product) and names both alternatives with the condition that selects them. It also explains the degraded case (feature disabled → empty templates plus a note), so the agent knows how to interpret an empty result rather than retrying.

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 cover read-only, idempotent and closed-world behavior, so the description's main contribution is data-interpretation semantics: that count means cited OR named for listed competitors, and that results are bucketed by kind. That is genuinely useful, but with no output schema there is still no disclosure of ordering, limits, or the other fields returned, so the return-behavior picture is only partly filled in.

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?

Purpose is front-loaded in the first clause, and the rest is dense, high-value caveats with almost no filler. The phrasing instruction ('say named or cited, not cited') is a little unusual and costs a sentence, but it guards against a real misreading of the data.

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, read-only report tool with no output schema, the description covers purpose, metric interpretation, and where to get the complementary per-answer detail. The only meaningful gap is the shape of the returned records beyond count and classification, which an agent would have to discover at call time.

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 the single siteId parameter's dual behavior (optional on a connected app, required with an API key, must match select_site) is fully spelled out in the schema. The description adds nothing beyond it, so the baseline of 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?

Names a specific resource (domains AI answers cite or name for this site's prompts), frames the value ('off-site targets worth earning presence on'), and states how the data is organized (classified by kind). It also separates itself from get_citations by pointing out that per-answer hosts live in otherCitedDomains there.

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?

Implied but clear routing: use this tool for the aggregated domain-level view of who is cited, use get_citations for the hosts each individual answer actually cited. There is no explicit 'do not use when' statement and no mention of prerequisites such as connected app vs API key, but the alternative is named with the condition that selects 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: site-limited connections return countsCover scoped to granted sites while limits stay account-level, budgetModelVersion 1/2 include scheduled and on-demand buckets while version 3 omits them, and engines.daily can be empty on a legacy period. These conditional output behaviors are exactly the kind of disclosure that helps an agent interpret 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?

The purpose is front-loaded in the first sentence, but everything after it is one dense, run-on second sentence packed with parenthetical asides (countsCover, checkedEveryDays, budgetModelVersion). The field explanations earn their place because there is no output schema, yet a bulleted or segmented structure would make them far easier to parse.

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 parameterless read tool with no output schema, the description carries the full burden of explaining the returned payload, and it does: allowance sections, coverage semantics, ledger versions, engine selection versus daily versus on-demand lanes, and the note that write-consuming tools are absent on read-only connections. Little an agent needs in order to interpret this tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate at call time. The baseline of 4 applies, and the description instead spends its words on the response payload, which is reasonable given no input parameters exist.

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?

"Every allowance on this Promvia account in one read" gives a specific resource (allowances/usage) and operation (single read). It is clear what the tool returns, but it never names or distinguishes itself from nearby siblings such as get_capabilities or get_metrics, so an 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?

The closing sentence implies the use case: these are the budgets that start_citation_run, start_deep_scan and generate_brief draw on, so checking here precedes invoking them. It also notes that read-only connections will not list those write tools. There is no explicit when-not-to-use rule or named alternative, so guidance is implied 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 only declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: null-score preconditions, integer rounding that can turn a positive share into 0, note-bounded forms, sample-size and Wilson-interval semantics, early-reading thresholds, thinBasis fragility, and modelVersion non-comparability. It also defines the statistical-tie rule and the interval rounding pitfall. This is well beyond what the annotations convey.

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 purpose is front-loaded in the first sentence, but the body is a dense, run-on sequence of caveats covering rounding, sampling, intervals, ties, and versioning. Much of it is genuinely useful for interpreting output, yet the volume and lack of structural breaks (no lists, heavy clause chaining) make it harder to scan than it needs to be.

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?

There is no output schema, so the description must carry the full burden of explaining return values, and it does: score, scoreBasis, thinBasis, modelVersion, shareOfVoicePct, shareOfVoiceSample (n, questions, interval, tooThin, earlyReading), and rivals with versusYou/rivalsBasis. It also covers edge cases like null rank and name-only competitors, making it complete for a complex scoring 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?

With schema description coverage at 100% and a single optional siteId fully documented in the schema, the baseline of 3 applies. The description adds no further meaning to siteId beyond what the schema already states about select_site and API-key requirements.

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 opening sentence gives a specific verb and resource ('Get a site's AI Visibility Score (0–100 + letter grade) and competitive rank') and defines the concept in one phrase ('how findable the site is across AI search engines'). It also explicitly separates itself from a sibling: 'the site audit alone is readiness (get_geo_audit), not visibility,' so an agent can tell the two apart 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?

It clearly routes the agent away from get_geo_audit and states the precondition for a non-null score ('until at least one unbranded (discovery) question has been measured') plus when rivals is empty. It also frames what the tool answers ('who is ahead?'). It stops short of a full use-when/use-when-not matrix against every sibling, but the alternative and conditions are 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?

Beyond the annotations, the description discloses ordering, page size, pagination behavior, archived-prompt behavior, and detailed semantics for many returned fields including null conditions and replacement history. The answerHash explanation adds useful behavioral context about exact text comparison and expected write hashes.

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 front-loaded with the tool's purpose and scope, then moves into field semantics and pagination/write alternatives. It is dense and written as a long run-on enumeration, but given the absence of an output schema, most of the field detail 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?

The description is complete enough for a paginated read tool: it covers scope, ordering, pagination, archived behavior, returned fields, hash semantics, and the alternative write tools. With annotations covering safety and the schema covering parameters, no critical agent-facing information appears 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?

With 100% schema coverage, the schema already defines the three parameters, but the description adds practical meaning by specifying page size, oldest-first ordering, that nextCursor is passed back as cursor and is null on the last page, and that archived prompts appear only with includeArchived: true. These are useful clarifications beyond the schema, though some duplicate the schema descriptions.

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 makes clear that this tool returns a site's tracked prompts, ordered oldest first and paginated at 100 per page, with their FAQ answers and related fields. It is specific about the resource and scope, but it does not explicitly differentiate itself from sibling tools such as get_prompt_templates or other read tools.

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 tells the agent to pass nextCursor back as cursor for the next page and that archived prompts require includeArchived: true, giving concrete usage instructions for pagination and archived content. It also redirects answer-writing to set_prompt_answer or sync_prompt_answers, though those are not listed siblings and it does not explicitly distinguish this list tool from all other sibling reads.

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 destructiveHint=false, so the safety profile is covered elsewhere. The description earns credit for disclosing a non-obvious behavioral rule: on a connection approved for chosen sites, only those sites are returned, while a full-account connection returns everything the seat can see. That nuance materially changes how an agent interprets an empty or short result; it stops short of covering ordering or result-size 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?

A single sentence front-loads the core action and returned fields, then appends the account-wide versus chosen-sites qualification. Nothing is redundant with the title or annotations, and no sentence could be dropped without losing information.

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 zero-parameter read tool with no output schema, the description supplies the essentials: what is listed, what fields come back, and how connection type affects scope. It leaves only minor gaps, such as result ordering or expected cardinality, which are unlikely to block a correct call.

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 the schema carries no semantics an agent needs help interpreting and the baseline is high. The description correctly adds no parameter discussion, wasting no space on arguments that don't exist.

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 gives a specific verb and resource ("List the sites this connection can use") and states what each entry contains (ids and domains), so an agent can immediately tell this is a scoped site enumeration. It doesn't explicitly contrast itself with siblings like get_capabilities or select_site, but no other sibling appears to be a site lister, so the ambiguity is low.

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 is implied rather than stated: the description frames the result in terms of what 'this connection can use', which hints this is a discovery step before operations like select_site. However, it never says when to call this versus a sibling, nor does it state any preconditions or exclusions outright.

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?

Beyond the readOnly/idempotent annotations, it discloses real behavioral traits: the selection is persisted per connection, no data in Promvia is modified, API-key calls persist nothing and return the siteId, and ambiguous or zero matches return candidates without changing state. That is exactly the stateful context the annotations cannot convey.

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?

Front-loaded with the purpose, then persistence semantics, then matching behavior; every sentence carries information. Slightly dense with the inline CLI examples, but nothing is redundant.

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 no output schema, the description still covers return behavior (siteId under API key, candidate list on ambiguous or no match) and the side effect on subsequent calls, which is everything an agent needs to 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: a unique fragment of a name is sufficient, matching is restricted to sites this connection can use, and ambiguous matches yield candidates rather than a failure. This goes past the schema's flat enumeration of accepted forms.

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?

"Choose the site to work on" is a specific verb plus resource, and the description immediately distinguishes this from list_sites (the source of the numbers) and from every site-scoped sibling by explaining that the choice becomes the default for all of them. An agent can tell exactly what this tool does without opening the 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?

It states the trigger (select a site before using other site tools), the lifetime of the effect (until another select_site), and the API-key variant where the caller instead passes the returned siteId. The only gap is that it never mentions the current_site sibling for reading back the active selection.

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 past the annotations: it discloses normalization (CRLF/CR to LF, trimming), that empty clears, that over-600-code-point answers are refused rather than truncated, the exact refusal payload, and that source is retained in change history. Concurrency semantics for expectedHash and the conflict payload are spelled out, and the idempotency claim in the annotations is corroborated with "sending the text already stored returns the same answerHash with changed: false and records nothing." The destructiveHint is also substantiated by "without expectedHash the write replaces whatever is stored."

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?

Purpose and the batch alternative are front-loaded, and nearly every clause carries operational information (limits, error shapes, hash semantics). The cost is density: the body is one long run-on paragraph mixing parameter rules, failure payloads, and return fields, which would read better as short labeled segments.

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 mutating single-record write with no output schema, the description supplies everything an agent needs: input sourcing, normalization and length rules, optimistic-concurrency behavior, the full success and failure payload shapes, and the batch alternative. Nothing material is left to inference.

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 100%, so the schema already documents all five parameters; the description nevertheless adds meaning beyond it, notably that the 600 limit counts Unicode code points, that refusal (not truncation) is the failure mode, that source lives in the answer's change history, and how expectedHash interacts with the stored hash. siteId is not discussed in the description at all, leaving the connected-app versus API-key requirement entirely to 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?

Opens with a specific verb and resource ("Set the FAQ answer of one tracked prompt") and anchors it to two concrete surfaces the agent may already know (the dashboard FAQ editor and the FAQPage JSON-LD). It explicitly contrasts single-write behavior with the batch sibling sync_prompt_answers, so the tool is distinguishable without reading any 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 clear routing guidance: queryId comes from list_prompts, and "Many answers at once is sync_prompt_answers" names the alternative and the condition that selects it. It also explains when expectedHash should be supplied (the hash you last read, or null for no answer) versus omitting it. It never states an explicit when-not-to-use case beyond the unknown/archived prompt refusal, 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 declare a non-read-only, destructive, non-idempotent, open-world operation, so the description's job is to add context — and it does: it enumerates the gate ladder (active-run convergence, verification, quotas, monthly COGS ceiling) and states that refusals name the gate, which tells the agent why a call may be rejected. It does not say whether the run is asynchronous or how to observe progress, which is the remaining behavioral gap.

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 action and followed by the behavior that matters for failure handling; nothing is padded. The parenthetical gate list is dense but each item earns its place by explaining refusal causes.

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?

There is no output schema, yet the description says nothing about what a successful call returns (a run id?) or which sibling to use to follow the run's progress. Given this is a long-running, non-idempotent, destructive-flagged operation, that is a meaningful omission, though the refusal semantics are well covered.

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 the siteId description already explains the connected-app vs API-key behavior in detail. The tool description adds nothing about the parameter, so the documented baseline of 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?

States a specific verb and resource: "Queue a full citation check-run for a site", which is clearly a write action distinct from read siblings like get_citations and get_citation_history. It does not name start_deep_scan explicitly, so the differentiation from the other run-starting sibling is left implicit.

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 makes clear this is the same operation as the dashboard button, which helps an agent understand when it applies, and notes that refusals identify the blocking gate. However, it gives no explicit when-not guidance, no mention of how this relates to start_deep_scan, and no prerequisites such as needing a selected site first.

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 description adds substantial behavior beyond the annotations: it names the gate ladder (feature flag, plan allowance, ownership verification, burst cap), states that refusals identify which gate failed, clarifies there is no provider cost, and describes the crawl as polite and limited to the site's own pages. This tells an agent far more about failure modes and cost than readOnlyHint/openWorldHint alone.

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 dense sentences with no filler; the core action is front-loaded and the gate-ladder detail follows. Every clause carries operational information an agent would otherwise have to discover by trial.

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 non-idempotent, open-world mutation with no output schema, the description covers cost, gating, and refusal behavior well, which is the critical part. The remaining gap is the post-call handoff: it does not say whether a scan handle is returned or that get_deep_scan is how results are retrieved, leaving the agent to infer the follow-up.

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 single siteId parameter has 100% schema description coverage, and that description already explains the connected-app default and API-key requirement. The tool description adds no parameter-level meaning on top of the schema, which is the expected baseline when coverage is high.

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 gives a specific verb ("Queue") plus resource ("deep site scan") and parenthetically defines the scope of the operation: a sitemap-first crawl capped by the plan's page ladder. This distinguishes it from read-side siblings like get_deep_scan, which retrieves rather than queues a scan.

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 is only implied: the word "Queue" signals an asynchronous start, so a reasonable agent infers it should call this first and poll with get_deep_scan. However, it never states when to use this over alternatives or what to do after calling it, so the guidance stops short of 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?

Beyond the destructive/idempotent annotations, the description discloses transactional all-or-nothing behavior, whole-batch refusal on one invalid item, tracking and revival semantics for untracked/archived prompts, conflict detection via expectedHash, idempotency-key retention and mismatch behavior, and history recording. These are meaningful behavioral details an agent could not infer from annotations alone.

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 content is valuable and mostly earnable, but it is delivered as one dense paragraph with long run-on sentences and parentheses, making it harder to scan than necessary. It is front-loaded with the purpose, but the structural density costs readability.

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 complex bulk-write tool with five parameters and no output schema, the description covers return statuses, counts, hash fields, refusal reasons, idempotency retention, and edge cases in enough detail for an agent to call and interpret it correctly. Nothing essential appears 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?

Although schema coverage is already 80%, the description adds substantial meaning: query matching ignores case and spacing, ambiguous text is refused with candidateQueryIds, expectedHash produces a conflict with no write, dryRun returns the exact planned result, and idempotencyKey governs replay and mismatch behavior. These semantics go well beyond the field descriptions.

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 resource: 'Set the FAQ answers of up to 100 tracked prompts in one transaction.' This clearly distinguishes the batch operation from the singular set_prompt_answer and from add_prompt, and an agent can identify the tool without opening the 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?

The description gives strong context for bulk syncing, including a release-with-repository-answers example, dry-run-first behavior, and idempotency-key-per-batch guidance. It references set_prompt_answer and add_prompt rules but does not explicitly say 'use set_prompt_answer for a single answer' or name other alternatives, so routing is clear but not exhaustively spelled out.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered by structured data. The description adds one genuinely useful behavioral fact (invalid keys fail with reason unknown-task), but is silent on what overwriting a prior status does and whether a status change is reversible.

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 short sentences, front-loaded with the action and its value set, followed by the key-provenance and failure rule. No filler or redundancy in the prose itself.

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 three-parameter mutation with no output schema, the description covers the action, valid values, parameter provenance, and the main failure mode. It leaves a minor gap around permission/site scoping consequences, which the schema only partially backfills.

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 67% and the schema already documents taskKey formats and the siteId resolution rules, so the description's taskKey sentence largely restates it. The status enum is only listed, not explained (e.g. what 'dismissed' versus 'done' implies), and siteId is untouched in the 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 specific verb and resource ('Set a GEO action item's status') and enumerates the exact target values (open, in_progress, done, dismissed). It also anchors the tool to its data source, get_geo_actions, so an agent can separate this mutation from the read siblings in the list.

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 clear operating context: taskKey must come from get_geo_actions and a key outside the site's action plan is rejected. It doesn't state any when-not conditions or explicit alternatives, but for a status-setter on a known key there is no real competing sibling to route against.

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