CiteLadder

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

Annotations already establish this is a non-read-only, non-idempotent, non-destructive write. The description adds real behavioral context beyond that: it runs synchronously ('runs at once') and enumerates the two refusal conditions, which an agent needs to anticipate failure modes.

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

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

Two tight sentences with no filler; the core action and downstream benefit are front-loaded, followed by the constraints. Efficient, though slightly dense in the first clause.

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 write tool with no output schema, the description covers the effect, the synchronous behavior, and the failure conditions, and routes the agent to a context-reading sibling. It is complete enough to call correctly, missing only return-value expectations.

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 name, aliases, domains, and project_id. The description only alludes to name uniqueness via the refusal condition and adds no syntax or format detail beyond the schema, 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?

Uses a specific verb (track/add) and resource (competitor) and explains the downstream effect: visibility reads rank the competitor's mentions and citations beside your brand. This clearly distinguishes it from the sibling remove_competitor.

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 concrete refusal conditions (name already tracked, competitor limit reached) and points to get_project_business_context to see who is tracked now. It gives clear context for when the call will succeed but does not explicitly name remove_competitor or other alternatives.

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 destructive=true and non-idempotent, so the safety profile is partly covered; the description still adds substantial behavior: it runs immediately, is irreversible, preserves already-recorded answers, spends no further prompt runs, and lists the two refusal conditions. It stops short of describing auth/permission requirements or the response shape, which keeps it at a 4 rather than 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?

Three tight sentences: effect and precondition first, side effects second, routing alternative and refusal third. Every clause carries information an agent needs, with no 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?

For a two-parameter destructive action with no output schema, the description covers what gets stopped, what survives cancellation, what it costs, when it is refused, and which tool to use instead. An agent has everything required 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 description coverage is 100% and both parameters are already documented in the schema, including that audit_id must be queued/running and where it comes from. The description repeats that constraint in prose but adds no new format or syntax detail, 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 specific verb and resource ("Stop a queued or running audit") and immediately scopes it to the two valid lifecycle states. It explicitly names the sibling that handles the related-but-different job (prepare_launch_audit), so an agent can distinguish it 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 concrete when-to-use conditions ("after the user agrees", launched by mistake, wrong engines), an explicit alternative for the follow-up action (prepare_launch_audit), and a when-not clause ("Refused if the audit is not in this project or has already finished"). Nothing about selection is left 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?

Goes well beyond the annotations (destructiveHint, non-idempotent) by disclosing token lifecycle behavior: single use and a ten-minute expiry, plus the agent-facing consent requirement. These are operational traits nothing else in the definition conveys, and they matter for calling correctly.

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 the action, then the consent gate, then the token constraint. No filler and no repetition of the schema.

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?

Covers the essential context for a one-parameter destructive tool: what it does, the consent gate, and token validity. It stops short of saying what happens if the token is expired or no preview exists, or whether the change can be undone, but the destructive annotation carries much of that safety signal.

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 parameter's own description already says it is the token the prepare tool returned, so the baseline is 3. The description adds real semantics beyond that: the token is single-use and valid for ten minutes, which clarifies what counts as a valid value.

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 ('make a change') and ties it directly to the prepare_* family of tools, so an agent can tell it apart from read_* and prepare_* siblings without opening a schema. The mechanism (executes a previewed change) is unambiguous.

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

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

Gives an explicit, checkable precondition: call only after the user explicitly agreed to that preview in this same conversation. That is a when-to-use rule with an implied when-not (no preview, no consent), which is exactly the guidance a destructive tool needs.

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 meaningfully beyond the annotations: it discloses that a deleted topic's prompts survive without a topic (the concrete consequence of a destructiveHint=true call), that it runs synchronously, and that it is refused on unknown topic names or duplicate names. Not covered: whether a failure is all-or-nothing, and the 50-item caps the schema enforces.

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, action-first, with the workflow anchor (after preview_topics) front-loaded and the return/error details trailing. Dense but each clause carries information; the parenthetical about offerings is slightly awkward but not wasteful.

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 states the return value (project topics with ids, for generate_prompts), which is exactly what an agent needs to chain. The main residual gap is failure granularity on a non-idempotent, destructive batch of up to 50 creates/renames/deletes.

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 real meaning: offerings must match what preview_topics listed (or be omitted entirely), and rename/delete operate on existing topics identified by id. That links the arrays to their origin and clarifies optionality 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?

States a specific verb and resource — saving a topic plan as one change — and immediately enumerates the three sub-actions (create, rename, delete). Naming preview_topics as the source plan and generate_prompts as the consumer distinguishes it cleanly from create_topic, rename_topic, and delete_topic.

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 anchors usage to the workflow: 'after preview_topics', which tells an agent exactly when this fires. However, it never explains when to prefer the single-operation siblings (create_topic, rename_topic, delete_topic) over this batch call, so the choice between batch and granular paths is left 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 mark this as a non-read-only, non-idempotent, non-destructive write. The description adds real behavioral context: it runs synchronously ('runs at once'), returns the topic id, and names are unique per project ignoring case, which implies duplicate-name behavior. It stops short of stating what error occurs on a duplicate name.

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

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

Three sentences, each earning its place: definition first, execution/return behavior second, uniqueness constraint last. No filler or restatement of the tool name.

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

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

For a 3-parameter mutation with no output schema, the description supplies the return value (topic id) and its downstream use, plus creation semantics. It omits error behavior on duplicate names and any permission requirements, which are the only remaining 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 100%, so the baseline is 3, but the description adds meaning the schema lacks: the name-uniqueness rule is case-insensitive, and the returned id's relationship to project_id/topic_id linkage is spelled out. The optional description parameter's purpose is left 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?

'Add a topic' states the specific verb and resource, then defines what a topic actually is ('a named group of tracked prompts ... that visibility is broken down by') with concrete examples. An agent can distinguish this from delete_topic or rename_topic from the name alone.

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 clarifies downstream usage by stating the returned topic_id is passed to prepare_add_prompts to file prompts under it, which establishes the creation workflow. It doesn't explicitly exclude alternatives (e.g., whether topics can be created implicitly elsewhere), so it falls short of full when/when-not 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 flag destructiveHint=true and idempotentHint=false, but the description adds the consequences annotations cannot express: prompts are kept and become topic-less, subtopics are promoted to top-level, recorded answers survive, execution is immediate and irreversible. That is exactly the extra context needed before a destructive call.

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 verb and its condition, followed by the data-retention effects, the irreversibility warning, and the alternative routing. Every clause carries distinct information; nothing is 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?

For a destructive, non-idempotent tool with no output schema, the description covers preconditions, side effects on related entities, reversibility, and alternatives. An agent has everything required to call it correctly and safely.

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 both parameters are documented in the schema (name, case-insensitive; project_id from list_projects). The description only restates 'by name' and adds no format or constraint detail beyond the schema, 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?

States a specific verb+resource (delete one topic by name) with scope (the grouping itself), and explicitly contrasts itself with rename_topic and prepare_archive_prompts. An agent can distinguish it from create_topic and rename_topic 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 precondition ('after the user agrees'), an explicit trigger ('when the grouping itself is no longer wanted'), and routes two adjacent needs to named alternatives: rename_topic for renaming and prepare_archive_prompts for ceasing measurement.

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/openWorld=false, so safety is covered. The description adds genuinely new behavioral context: the id must be provenance-tracked from a prior read and must never be synthesized, which is not derivable from the schema or annotations.

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

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

Two short sentences, front-loaded with the action and scope, followed by the critical id-provenance constraint. No 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?

For a single-parameter fetch-by-id tool with no output schema, the description covers what is read and where valid ids come from. It could note pagination or partial-record behavior, but a 'full record' read is adequately characterized.

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% for the single id parameter, so the schema already documents it. The description reinforces the provenance rule ('as a read returned it'), but adds no format or syntax detail beyond the schema. 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 a specific verb (Read), a scoped resource (one full record), and enumerates what a record can be (answer, Action, prompt, page). This distinguishes it from the many read_* siblings that return collections or specific datasets.

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?

Clearly establishes the usage precondition: the citeladder:// id must come from another read, and warns 'Never construct an id.' That is strong guidance for when this tool applies, though it does not name a specific alternative sibling for cases where no id exists.

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 suggestions are only staged and "never tracked" until the user Accepts via review_url, that the call consumes AI credits, and that the shortfall is reported but never filled. The run_key idempotency contract is spelled out in operational terms (same key on retry returns the staged result), which complements rather than repeats idempotentHint.

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 agreed-run precondition are front-loaded, and most sentences carry operational weight (credit spend, retry, staging, shortfall). The distribution sentence duplicates what the schema already says about branded/comparison/intent shares, making it the one line that could be trimmed.

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 9-parameter, credit-consuming, non-destructive mutation with no output schema, the description covers what an agent needs: consent gate, cost, staging/activation lifecycle, retry semantics, and the fact that shortfalls surface as reported reasons. Return behavior is described qualitatively (staged result, review_url), which compensates for the absent output 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 coverage is 100%, so a 3 is the baseline; the description adds genuine value by explaining the provenance of parameters — seed_source/seed_query_ids from read_seed_queries, topic_ids from confirm_topics or read_prompt_portfolio, prompt_set_id from read_prompt_portfolio — and clarifying that run_context is a one-off note never saved as a business fact. The distribution explanation largely restates the schema text, which is why it isn't a 5.

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 + resource ("Run CiteLadder's prompt generator for the project") and anchors it to the UI equivalent ("the Prompt Builder's Generate step"), which clearly separates it from siblings like prepare_add_prompts, update_prompt_text, and read_prompt_portfolio. An agent knows this generates suggestions rather than mutating prompts directly.

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 precondition ("once the user agreed to the run") plus a rate/usage rule ("call it once per agreed run") and retry guidance (resend the same run_key). It also routes the agent to the correct upstream sources for parameter values (read_seed_queries, confirm_topics, read_prompt_portfolio). It stops short of explicitly contrasting with the manual alternatives such as prepare_add_prompts.

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 with readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds useful behavioral context beyond that. It discloses partial-failure behavior, including unavailable visibility when there is no completed run or when metrics are still pending and should be retried later.

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 core purpose and then explains scope and failure behavior. It is dense but not padded; the long enumeration of sections earns its place by summarizing what each section returns.

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 multi-section overview tool with no output schema, the description is complete enough to call correctly. It explains the aggregate nature, the available sections, section selection, and expected partial unavailability such as no_completed_run and metrics_pending.

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 project_id and the sections enum. The description still adds useful meaning by clarifying that omitting sections returns all, passing fewer sections reduces response size, and profile includes owned domains and competitors.

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 and resource: read one project overview in a single call. It distinguishes this aggregate tool from the many sibling read_* tools by stating that each section is a short summary and the matching read_* tool provides depth or paging.

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 guidance: use this first to orient, then use the matching read_* tool for depth or paging. It also explains how to control scope by omitting sections for all or passing a few to keep the response small.

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 closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: returned fields, oldest-first ordering, 50-per-page default, and the notable semantics that an empty list means no approved workspace rather than an error.

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?

Five short sentences, front-loaded with the entry-point role before the return fields and pagination details. Dense but nearly every clause carries operational information; the field enumeration could be trimmed if an output schema existed, but it does not.

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 compensates by enumerating the returned fields, and it covers pagination, ordering, and the empty-list case. An agent has everything needed to call and interpret this tool 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 baseline is 3, but the description adds meaning the schema lacks: the concrete default page size of 50 and the oldest-first ordering that makes cursor pagination predictable. Minor friction: it calls the cursor 'next_cursor' while the schema property is named 'cursor'.

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 projects this connection can read') and immediately distinguishes itself from siblings by noting it is the entry point that produces the id every other project tool needs. An agent can tell it apart from search and get_project_business_context without opening a 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?

Explicit when-to-use ('Start here when no project is known'), plus named alternatives for adjacent intents: 'To find a project by name use search; for one project in depth use get_project_business_context.' Routing is unambiguous.

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), so the bar is low. The description adds genuinely non-derivable context: this is a UI/rendering action and only works in app-capable clients, which prevents an agent from expecting a data payload back.

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 what is shown and immediately followed by the routing alternative. Every clause earns its place with no 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?

For a zero-param, fully annotated tool with no output schema, the description covers purpose, client constraint, and the alternative tool. It could briefly note whether anything is returned or what happens after the user picks (likely nothing to the agent), but nothing essential 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 and schema coverage is 100%, so the baseline is 4. There is nothing for the description to clarify about inputs, and it does not misrepresent any.

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 (show/display) and resource (the CiteLadder project picker), plus the goal (let the user choose a project). It is immediately distinguishable from siblings, especially the read_* family and list_projects, since it is a UI-display action rather than a data fetch.

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 usage condition ('in clients that display apps') and names the alternative for the agent-driven case ('Use list_projects to find projects yourself'). It does not spell out a when-not-to-use case beyond that, so it stops just short of a full routing rule.

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=false/destructive=false; the description adds the crucial lifecycle detail that nothing mutates until confirm_change, and that confirmed prompts are measured from the next audit — behavior an agent could not infer from structured fields. It does not say whether a prepared change expires or can be re-run over an existing pending change.

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 action and its output, followed by the safety/commit contract. No filler and nothing 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, the description compensates by naming exactly what the preview returns (addable, dropped + reason, resulting slots), and the two-phase commit requirement is spelled out. For a staging mutation tool this covers everything needed 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% and each parameter and nested prompt field is documented in the schema, so the baseline is 3. The description's '1–50 prompts' and 'to a prompt set' restate limits and scoping already encoded in minItems/maxItems and prompt_set_id's description, adding little new 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?

States a specific verb+resource ('preview adding 1–50 prompts to a prompt set') and enumerates the preview payload (which can be added, which are dropped and why, slot counts after). The explicit hand-off to confirm_change separates it from the sibling that actually commits the change.

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?

'Nothing changes until the user agrees and you call confirm_change' gives the gating condition and names the follow-up tool, so the agent knows this is step one of a two-phase flow. It stops short of contrasting with prepare_archive_prompts or stating when not to use it (e.g., already-prepared change pending).

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 mark destructiveHint=true and idempotentHint=true, so the agent already knows the safety profile. The description adds valuable nuance beyond that: nothing mutates at this step (only at confirm_change) and the semantic effect is disclosed (future audits stop measuring; past results retained). It does not describe auth/role requirements or the preview's return shape, keeping it short of 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?

Two tight sentences with zero filler. The core action is front-loaded and the conditional workflow constraint follows, so 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, the description should ideally hint at what the preview returns; it does not, which is a minor gap. Otherwise it fully conveys purpose, effect, and the confirm_change dependency needed to call the tool correctly.

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

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

Schema description coverage is 100% and both required params are documented in the schema, including their source tools (list_projects, read_prompt_portfolio). The description adds no syntax or format detail beyond the schema, so it sits at 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?

States a specific verb and resource ('Preview archiving tracked prompts') and immediately clarifies the scope of effect ('future audits stop measuring them; past results stay'). It also distinguishes itself from the eventual mutation by naming confirm_change, so an agent can tell it apart from the confirm step without opening a 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?

Clearly establishes the workflow condition: this is a preview whose effect only lands after the user agrees and confirm_change is called. That routes the agent to the correct follow-up tool. It lacks an explicit 'do not use for X' exclusion, but the two-phase framing is unambiguous.

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 real behavior beyond the annotations: this call is a preview that changes nothing, effect only lands after confirm_change, and CiteLadder will later check evidence against the declaration. Annotations already cover idempotentHint=false and destructiveHint=false, so the extra workflow/side-effect context is the valuable part; permissions and the readOnlyHint=false vs "nothing changes" tension are left unexplained.

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 filler: the preview purpose is front-loaded, then the safety/confirm condition. 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 covers the workflow and safety profile adequately for a null-safe prepare tool, but it does not say what the preview actually returns or what the user is meant to review before confirming. Minor gap, otherwise 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%, so each of the three parameters is already documented in the schema. The description adds no parameter-level detail (e.g., that action_id must come from read_actions, or how declared_implemented_at affects evidence checking), 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?

States a precise verb+resource+scope: "Preview declaring that the work of an open Action is done." The name/title are restated with added substance (an *open* Action, the work being done), so an agent knows exactly which operation this is.

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 usage context and an explicit follow-up requirement: nothing changes until the user agrees and confirm_change is called, which tells the agent how this fits into a workflow. It does not, however, contrast with possibly-confusable siblings such as update_action_status or the other prepare_* tools, so no explicit exclusions.

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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, but the description adds crucial context annotations cannot express: this is a dry-run preview with no side effects until confirm_change is called, and the launch is refused if it needs more than max_attempts. That is meaningful behavioral disclosure beyond 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?

Three sentences, front-loaded with the core action, followed by parameter guidance and the confirmation gate. No wasted text; each sentence earns its place.

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

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

With 7 parameters, no output schema, and safety annotations present, the description covers the preview semantics, market behavior, and confirmation flow well. It omits detail on repetitions, prompt_ids, and prompt_set_id, but those are adequately served by the 100%-covered 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 coverage is 100%, so the baseline is 3. The description goes further by explaining intent behind parameters: market_ids produces one audit per market (null = default market) and max_attempts caps provider attempts with refusal on exceedance, adding meaning beyond the schema's own prose.

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+resource: 'Preview launching an audit of a prompt set (or chosen prompts) on the given engines.' It clearly positions itself as the preview step, distinct from confirm_change and cancel_audit among siblings.

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 operational context: pass market_ids to run one audit per market, pass max_attempts to cap attempts, and 'Nothing runs until the user agrees and you call confirm_change' explicitly routes the agent to the follow-up tool. No explicit when-not-to-use, but the workflow gate is well defined.

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=false, destructiveHint=false, idempotentHint=false. The description adds genuinely useful behavior beyond them: this call is a preview that changes nothing, it commits only after an explicit confirm_change, and it consumes one prompt run per recorded answer — real cost information an agent needs before invoking.

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 purpose, then the market_ids behavior, then the cost and commit gate. Every sentence carries distinct information with no 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?

For a 9-parameter scheduling tool with full schema coverage and annotations, the description supplies the missing pieces an agent needs: preview semantics, the confirm_change commit path, and prompt-run cost. No output schema exists, so return-format detail is not required; only an explicit contrast with prepare_launch_audit is absent.

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. The description goes slightly further by explaining the effect of market_ids (one audit per market) and that null/omitted means the default market, which is semantic behavior rather than a restatement of the schema types.

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 (preview/prepare) and resource (recurring audit schedule for a prompt set), and the 'Preview' framing plus the confirm_change reference distinguishes it from the raw mutation siblings. It does not explicitly contrast with the closest sibling prepare_launch_audit (one-time vs recurring), so sibling differentiation is only 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?

Gives clear operating context: create the schedule here, nothing takes effect until the user agrees and confirm_change is called, and market_ids drives one audit per market. It stops short of an explicit when-not rule (e.g. one-time launches vs recurring schedules), but the workflow step is unambiguous.

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 the annotations cannot convey: it costs one AI model call, persists nothing, caps its proposal list with a 'more' indicator, and has a stated precondition that causes refusal. The one tension is that 'saves nothing' reads as read-only while readOnlyHint is false, though the false hint is plausibly driven by the external model call rather than a data write, so it is not scored as a contradiction.

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 and front-loaded: what it does, what a topic is, the cost, the workflow, then the precondition. Every sentence carries information, though the mid-sentence 'more lists proposals past the cap' clause is slightly cryptic and interrupts the flow of the workflow instructions.

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 compensates by describing what comes back (existing plus proposed topic names, with a 'more' overflow marker) and what happens to it (nothing saved until confirm_topics). Combined with the cost and refusal conditions, an agent has everything needed to call this correctly and set user expectations.

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?

Single parameter with 100% schema description coverage ('A project id that list_projects returned'), so the schema already does the work. The description adds only indirect meaning via the offering prerequisite, which implies project-level preconditions but not per-parameter syntax. Baseline 3 for full-coverage schemas.

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 ('Propose buyer-facing topics for the project') and scopes it relative to existing topics. It goes further by defining what a topic is and what it is not ('never a product line, model, size or the brand'), which lets an agent distinguish this from create_topic, rename_topic and confirm_topics 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?

Explicitly routes the workflow: preview here, then hand the list to the user to keep/rename/delete/add, then call confirm_topics to persist. It also gives a hard prerequisite ('Refused until the project lists at least one offering'), so the agent knows when the call will fail before making 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 and non-destructive, so the bar is lower, yet the description adds real behavioral context: the default filter is open plus in-progress when no status is supplied, results are priority-ordered, and pagination runs through next_cursor. It also discloses the shape of both the list items and the single-Action detail, which no structured field provides.

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 ordering, then default-filter semantics, then the detail mode and sibling routing. The response-field enumeration is a long run-on sentence, but with no output schema it earns its place; only light tightening would help.

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 return-value burden and does so for both modes: list item fields, status_counts, paginated next_cursor, and the diagnosis/findings/outcome/declaration structure of a single Action. Nothing an agent needs in order to call this 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 baseline is 3, but the description adds meaning the schema does not: it explains that omitting status yields open and in-progress only, that next_cursor is fed back into cursor, and that action_id switches the response from a list to a full single-Action read. That is genuine semantic value on top of the schema text.

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 work CiteLadder recommends to improve visibility"), names the ordering ("highest priority first"), and covers both operating modes: paged listing and single-Action detail via action_id. An agent can distinguish this from the many read_* siblings 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?

Explicitly routes follow-on work to two named siblings: update_action_status to dismiss or reopen, and prepare_declare_implemented when the work is done. It also explains the action_id mode as the way to see one Action in full. What is missing is guidance on when to prefer this over adjacent read tools such as read_visibility_overview, so it falls short of full when/when-not coverage.

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 read-only, idempotent, non-destructive behavior, yet the description adds substantial domain context beyond them: the not_applicable-vs-zero semantics for non-ChatGPT engines, the paged nature of creatives, and the reporting rule that ads are paid placements to be reported separately, never as citations or a cause of visibility.

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 returned contents before the caveats, and the key reporting constraint is placed last for emphasis. The middle enumeration is dense but each clause maps to a distinct returned element, so little is wasted.

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 and a non-trivial seven-parameter surface, the description supplies the return contents, engine applicability, and reporting rules an agent needs. Nothing required to call or interpret 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 all seven parameters are already documented, including the cohort enum and engine list. The description adds domain framing (runs, engines, paged creatives mapping to cursor/limit) but no syntax or format detail the schema lacks, 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?

States a specific verb (read) and resource (paid ads shown in AI answers) and then enumerates the concrete contents — presence rate, advertisers with share and first/last seen, brand ad share/rank, text creatives, prompts surfacing ads. This clearly distinguishes it from siblings like read_ai_shelf and read_ai_referrals that also concern AI visibility.

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?

Explains scoping via 'latest or a chosen run' and the crucial engine rule: only ChatGPT Search shows ads while other engines are not_applicable, never zero. This tells the agent how to interpret results, though it does not explicitly name an alternative sibling tool to use instead for other visibility data.

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, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds meaningful edge-case semantics that annotations cannot convey — 'unavailable no_site_crawl' means no crawl exists and 'robots_not_observed' means robots.txt could not be read — which is genuine behavioral value, though it stops short of describing ordering, sampling limits, or response shape beyond the field list.

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 core question and no filler; every sentence carries information, including the permission-vs-observed contrast and the status-code glossary. The first sentence is heavily nested with a long enumerative list, which slightly hurts scannability but does not waste space.

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 return-value burden and does so: it lists the reported fields, the per-crawler attributes, and both failure statuses. For a two-parameter read tool with strong annotations, nothing an agent needs to select or interpret the call is missing.

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

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

Schema description coverage is 100%, so the schema already documents both project_id and crawl_id (including the 'omit for latest' rule), making 3 the baseline. The description's 'latest or a chosen crawl' restates rather than extends the schema, adding no new syntax or format detail.

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 ('Read whether the site's robots.txt lets each AI crawler in') and enumerates exactly what is reported: fetch status, listed sitemaps, and per-crawler operator, purpose, matching rule, root access and blocked samples. It also names the sibling it is not (read_crawl_logs), so an agent can distinguish permission data from observed visits 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?

Explicitly routes the agent: use this for permission, use read_crawl_logs for crawlers that actually came. It also clarifies the crawl_id choice (latest vs. chosen crawl from read_site_health), so there is no ambiguity about when either parameter path applies.

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 closed-world, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the unavailable state means 'no referral data imported, which is not zero', preventing a false-zero interpretation. No rate-limit or freshness detail, but the empty-vs-zero distinction is a meaningful addition.

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 what the tool returns, then sibling disambiguation, then the edge case in three tight sentences with no filler. Dense but every clause carries routing or interpretive value; slightly compact phrasing ('for a range') is the only minor friction.

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 steps up by enumerating the return fields (sessions, share, key events, top landing pages) and explains the unavailable-state behavior. Combined with the GA4 data-source note, an agent has what it needs to call and interpret the result; only pagination/format specifics are absent.

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%, with range enum values and start/end date semantics already documented in the schema. The description only adds 'for a range', which is implied by the schema, so it does not meaningfully extend parameter meaning beyond the baseline for full coverage.

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 resource (visits from AI assistants, sourced from GA4) and enumerates the returned measures: sessions, share of all traffic, key events, top landing pages. It also differentiates from the nearest sibling by noting read_crawl_logs covers crawler requests, so an agent can route correctly without opening a 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?

Explicitly names the alternative read_crawl_logs and the condition that selects it ('people clicking through' vs 'crawler requests'), and points to read_integration_status when data is unavailable. This covers both the sibling-disambiguation and the failure-mode path.

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 as a safe, read-only, idempotent, closed-world tool. The description adds substantial behavioral context beyond that: the two-step catalog/target workflow, return fields such as share of shelf and first-position win rate, product omission counts, and the meaning of the no_product_catalog error.

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 purpose and then explains the two call modes and error case. It is dense but every sentence contributes useful information; it could be slightly more scannable, but there is no wasted 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?

There is no output schema, so the description carries the burden of explaining return values. It does so thoroughly for both the no-target catalog call and the targeted call, including metrics, holders, measurement timing, and an error semantic, making it complete for correct invocation.

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 three parameters. The description still adds useful semantics by explaining that target_id should come from the catalog returned without a target and that target_kind/target_id must be passed together, though it does not add much beyond the schema for project_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?

The description states a specific verb and resource: reading AI answer shelf recommendations for products and merchants in an ecommerce project. It clearly separates this from related visibility tools by naming read_visibility_overview for brand mentions, so an agent can distinguish it from siblings.

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 sequencing: call first with no target to get the catalog, then call again with target_kind and target_id for a category or product. It also states the alternative for non-ecommerce brands when no_product_catalog is unavailable, which is exactly the when-not guidance an agent needs.

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/closed-world, and the description still adds substantial behavioral context: default window selection, the exact-match constraint on custom dates, the meaning of the 'unavailable' state, that coverage.notice explains the cause (e.g. GA4 not connected), and the 'co-occurrence, not cause' interpretation caveat.

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 return shape are front-loaded, and each sentence carries distinct information (patterns, return content, window rules, failure state, sibling routing). It is dense rather than padded, though the single long paragraph is heavier than strictly needed.

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 compensates by describing what each pattern contains (explanation, numbers, pages, coverage) and how the empty/unavailable state plus coverage.notice should be interpreted. An agent has everything required to call 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 the baseline is 3, but the description adds a constraint not present in the schema: custom start_date/end_date must match a saved window exactly, and range resolves to the newest saved 30-day window. That extra semantic layer slightly exceeds the schema-documented parameter text.

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 ('Read the patterns CiteLadder found by joining AI crawler, referral and citation data for one saved window') and enumerates the exact pattern types returned. It also explicitly differentiates itself from the sibling read_ai_traffic_pages, so an agent can route between them 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?

Names the alternative ('Use read_ai_traffic_pages for the per-page numbers') and states the selection condition, plus explicit window rules: newest saved 30-day window by default, custom dates must match a saved window exactly. Both when-to-use and when-not-to-use are covered.

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 the safe read-only/idempotent profile, and the description still adds genuinely non-obvious behavior: per-measure coverage, the rule that a measure without a connected source is 'missing, not zero', observed_crawl_coverage as a log-completeness signal, default 30d window, and 10-per-page/100-cap pagination via next_cursor. These are the traps an agent would otherwise fall into.

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, then row shape, then windowing/pagination, then sibling routing — a sensible information order with no filler sentences. It is dense and slightly long, but every clause carries operational meaning rather than restating the name.

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

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

No output schema exists, so the description carries the return-value burden — and it does, naming the row fields (URL, path, folder, resource class), the four measures, and the last crawl. Combined with coverage and pagination semantics, an agent has everything needed to call and interpret this 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 supplies defaults the schema omits (30d window, 10 rows per page up to 100, pass next_cursor for more). It does not add syntax beyond the schema for sort/filter enums, so it lands just above baseline rather than at the top.

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 ('Rank the project's own pages by AI activity') and immediately disambiguates the scope: the project's own pages, ranked by AI activity, not site-wide totals. The three sub-questions (crawler fetches, assistant referrals, answer citations) make it unmistakable versus read_ai_referrals or read_crawl_logs.

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 routes to four named alternatives with the condition that selects each: read_ai_traffic_url for a single page timeline, read_crawl_logs for crawler-level detail, read_ai_referrals for site-wide totals, read_site_pages for titles/scores. This is a complete when-to-use map rather than an implied 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 readOnly/idempotent/non-destructive, and the description goes well beyond them: default window of 30d, the fact that each timeline is capped with provenance.bounded=true when a cap is hit, and precise error semantics (url_not_joinable vs 'unavailable' with no reason). This is exactly the kind of operational context an agent needs to interpret results and 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?

Front-loads the purpose, then layers output shape, window default, cap behavior, and error semantics in dense but information-dense sentences that each earn their place. Slightly long, but no filler or restated boilerplate.

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 carries the full return-value burden — and it does so, describing the four measures with coverage/error data, crawler visit spans, AI source referrals, and citations by date/run. Combined with window defaults and error semantics, it is complete enough to invoke and interpret without further docs.

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 real meaning: the default window (last 30d), the requirement that url come from read_ai_traffic_pages, and the site-membership constraint on url. It adds value beyond the schema without fully re-specifying every parameter.

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+resource (read the AI traffic timeline for one URL) and immediately distinguishes itself from the sibling read_ai_traffic_pages by positioning this as the per-page drill-down. The description even enumerates the four measures returned, so an agent knows exactly what this tool produces.

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 prerequisite/ordering condition: use this 'after read_ai_traffic_pages names it,' which routes the agent to the right sibling for discovery first. It also states the constraint that the URL must be on the project's own site. There is no explicit when-not-to-use beyond that constraint.

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 substantial context: the cap of 10 newest reports, the report payload structure (parity/gaps/only-you features with share of inspected pages), the meaning of the insufficient_evidence state (<3 readable competitor pages or no owned page match), the meaning of an empty list, and the guarantee that it never fetches new pages.

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 usage are front-loaded and every sentence carries information, but the block is dense and run-on; the report-field enumeration and edge-case definitions could be broken out for faster scanning.

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 correctly carries the return-value burden, describing report shape, the cap on results, and both degenerate outcomes (insufficient_evidence, empty list). An agent has everything needed to call it and interpret results.

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 there is a single required project_id fully documented by the schema. The description adds no parameter-level detail, but with only one trivially documented parameter there is little the description could usefully contribute.

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 (Read) plus a precise resource (how competitor pages cited by AI answers differ from your own page, on topics they win). It is immediately distinguishable from sibling read_* tools, which cover traffic, visibility, crawlability, etc., rather than page-content comparison.

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

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

Explicitly says when to use it ('before rewriting a page to compete') and names the prerequisite alternative ('Use read_visibility_sources to find the competing pages first'). Both the trigger and the routing to a sibling are stated, 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: the 30d default window with the exception that requests without range/dates reads every retained day, failed-verification requests being silently excluded unless requested, and the caveat that 'not_connected or missing coverage means unknown, not zero' — a real misinterpretation trap.

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 then view-by-view breakdown, and nearly every sentence carries operative information. It is dense and long for a description, but the length is driven by four distinct modes and pagination rules rather than 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?

For a 12-parameter tool with no output schema, the description supplies what is otherwise missing: the shape of each view's result (totals and daily series, one row per crawler, per-day completeness, individual requests) plus pagination and cursor behavior. Nothing material needed to call it correctly is absent.

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 per-parameter meaning is already documented; the description nonetheless adds cross-parameter rules the schema cannot express (changing a filter requires a new first page, a continuation may change limit, range vs start/end date alternation, bot_id sourced from the crawlers view). It does not restate every filter, but the added interaction semantics are the valuable part.

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 ('Read the AI crawler requests your server logs recorded') and immediately enumerates the four views and what each returns. It also names the two nearest siblings (read_ai_crawlability, read_ai_traffic_pages) and the distinct question each answers, so an agent can route without opening schemas.

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

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

Explicitly maps intent to view: totals → summary (the default), per-crawler status → crawlers, log completeness → coverage, individual hits → requests. It adds exclusions ('Use read_ai_crawlability for robots permission and read_ai_traffic_pages for activity per page') so the agent knows when NOT to use this tool.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description is free to add genuinely new behavior: the unavailable/no_demand_snapshot condition and its likely causes, the coverage flags, and the explicit warning that the change in signal count is correlational, 'not a cause'. That is behavior beyond anything the annotations state.

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, and nearly every sentence carries routing or error-handling value. It is dense and slightly run-on, but there is little genuine filler 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?

With no output schema, the description must describe returns, and it does: the window token, signal counts by type, detector states, coverage, and the previous-snapshot delta. Combined with the error and sibling routing, an agent has everything needed to call and interpret it.

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 there is a single required project_id whose meaning the schema already documents. The description adds no format or syntax detail beyond the schema, 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?

States a specific verb and resource ('read the latest search-demand snapshot') and enumerates the concrete signal types it contains (striking-distance queries, competing pages, low CTR, rising/falling queries). It explicitly distinguishes itself from the three adjacent read_* siblings it could be confused 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?

Names the alternatives and the condition that selects them: pass the returned window to read_query_evidence for query rows, use read_actions for prioritized work, and read_search_intelligence for keyword volumes from research. It also explains the no_demand_snapshot failure and routes the agent to read_integration_status.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them: it defines accuracy as supported/(supported+contradicted), warns that accuracy_state values like not_enabled/no_facts/no_claims/pending mean 'no value, never zero', clarifies that inconclusive and not_covered are not errors in the answer, and explains that sources cite alongside a contradiction rather than causing it. That is substantial interpretive context not available 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-loaded with purpose and the sibling contrast, then the summary/claims contents, then a compact block of interpretation caveats. Sentences are dense and each carries semantics, though the paragraph is long enough that some caveats could be ordered more tightly.

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 return-value burden and does so: it details what the summary view returns (accuracy, coverage by topic and engine, contradicted claims with the contradicting fact, sources) and what the claims view returns (quote, verdict, facts used) plus pagination. Nothing an agent needs to call or interpret the 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?

Schema description coverage is 100%, so the baseline is 3 and the schema already documents view, limit, topic, cohort, cursor, engine, verdict, audit_id and market_id. The description still adds real meaning on top: it explains the summary vs claims distinction, states the default page size (50) and that next_cursor should be passed back, and ties verdict/cohort behavior to the claims view.

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+resource+scope: reads fact-checking verdicts of AI answers against the brand's confirmed facts, broken into summary and claims views. It explicitly distinguishes itself from the neighbouring read_perception tool by dimension (accuracy vs tone), so an agent can pick correctly without opening schemas.

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

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

Names the alternative and the condition that selects it ('Use read_perception for tone rather than accuracy'), and adds operational guidance on how to report ('always state the coverage and quote the fact') plus which verdict value to pick to find errors. Nothing about tool selection is left 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 readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds value beyond that: the full stage vocabulary, backfill/import-through semantics, snapshot existence, and the fact that connection setup is out-of-band. It doesn't discuss pagination or cost, but for a diagnostic read this is 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?

Front-loaded with purpose then return shape then trigger, and no sentence is filler. It is dense and long for a single-parameter read, which keeps it just short of a 5.

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 carries the burden of explaining the return payload — and it does so thoroughly, including the enum of stages and per-connection fields. Nothing an agent needs to call or 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?

Only one parameter with 100% schema coverage, and the schema itself notes project_id comes from list_projects. The description adds no syntax or format detail beyond that, 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?

States a specific verb+resource ('Read which data sources ... are connected to the project and how far their import has got') and enumerates the exact return surface including the stage enum values. An agent can distinguish it from read_performance or read_search_dataset 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 trigger ('Read it when another read returns unavailable or not_connected, before reading that again') and a clear exclusion ('Connecting a source happens in CiteLadder, not through this tool'), so both when-to-use and when-not-to-use are covered.

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, the description discloses the truncation limit (36000 characters), the text_chars_omitted counter, snapshot semantics ('as of fetched_at'), and two failure states with recovery paths (page_not_crawled with crawled_urls, no_site_crawl). That is exactly the behavioral context the 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 and payload are front-loaded in the first clause, followed by output contents, then constraints and error handling in a logical order. It is dense and slightly run-on, but essentially every sentence 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?

There is no output schema, so the description compensates by describing the returned fields and the truncation counter, plus the two error codes and how to recover from them. For a four-parameter read tool this leaves nothing material unstated.

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: url and site_url_id are alternate addressing modes, and crawl_id overrides the default of the latest crawl. It reinforces rather than duplicates the schema's own 'pass this or url' 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 states a specific verb and resource: 'Read the words of one crawled page'. It enumerates exactly what is returned (title, meta description, h1-h3, body text, URL, page type, fetched_at), which clearly separates it from read_site_pages, and it refers to that sibling for obtaining site_url_id.

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 names concrete use cases ('quote, review or rewrite what a page actually says') and states a key constraint that governs selection: it reads the latest crawl or a given crawl_id, and never fetches the live page. There is no explicit 'do not use this for X' routing, so it falls short of a 5, but the 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 (readOnlyHint=true, idempotentHint=true) already cover the safety profile, yet the description adds substantial operational context: the response is always available, and pending/unavailable/no_mentions must never be read as zero; coverage must always be stated; and sources are cited alongside criticism but are never its cause. These are non-obvious behavioral traits an agent could easily misread, and they are disclosed clearly.

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 primary content is front-loaded in the first sentence, with view/paging semantics and the routing alternatives following. The prose is dense with several ideas per sentence and could be broken up, but every clause carries decision-relevant information, so little is wasted.

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 and 11 parameters, the description carries the full burden of describing returns, and it does: sentiment scale, per-dimension coverage, theme breakdowns, recommendation signal, source attribution, the two view shapes, and paging. Combined with 100% schema coverage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents view, cohort, cursor, engine, entity, polarity, and market_id. The description still adds value beyond it by stating the default page size (50) and the next_cursor round-trip, which the schema only alludes to as 'the default page size.' That is a modest but real increment over the schema 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 states a specific verb and resource ('Read how AI answers portray the brand and competitors') and enumerates the concrete outputs: net sentiment (-100 to +100) per brand/engine/topic/prompt with coverage, praise and criticism by theme, recommendation/advice rates, and cited sources. It also explicitly differentiates itself from read_fact_checks and read_visibility_overview, so an agent can distinguish it from siblings without opening a 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 names the two alternatives and the exact conditions that select them: 'Use read_fact_checks for whether answers are factually right, and read_visibility_overview for how often the brand is mentioned at all.' It also explains the summary-vs-quotes view split and the paging mechanism (50 default, pass next_cursor), leaving no routing ambiguity.

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), and the description adds substantial behavior on top: the default window (last_synced, all imported data), the performance_range_not_projected failure mode, the crucial semantic that not_connected means no source is connected rather than zero, and the 10-row page default with next_cursor continuation. It stops short of explaining how compare/granularity interact with the returned series, 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?

Front-loaded with purpose and return shape, then defaults, then failure modes, then sibling routing — every sentence carries information. It is a dense single paragraph of roughly five sentences; a short bulleted split of return-shape vs. error semantics would scan faster, but nothing here is 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?

With 12 parameters, no output schema, and no nested objects, the description supplies what the schema cannot: the return structure (totals, series, data coverage, row counts per breakdown), paging defaults, the default window, and two named error states with their interpretations. An agent has everything needed to call this correctly and interpret failure responses.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the conditional semantics of dimension (totals+series when absent, one page of rows when present), the concrete default of 10 rows, and that next_cursor continues paging. Sorting, comparison dates, and granularity defaults are left 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?

States a specific verb and resource (read organic search performance) and enumerates the exact metrics returned (clicks, impressions, CTR, average position, sessions, key events) plus the two output shapes (totals+series vs. paged rows by dimension). It also names what it is not, routing the agent to read_query_evidence and read_ai_referrals, so it is distinguishable from siblings without opening a 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?

Explicit conditions are given: use preset ranges because most custom windows have no saved snapshot, use read_query_evidence for queries matched to crawled pages, and read_ai_referrals for AI-assistant traffic. Both alternatives are named with the condition that selects them, which is the strongest form of routing 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuinely useful traits beyond that: oldest-first ordering, page-then-cursor paging, inclusion of topics with no prompts yet, and the topics_truncated partiality flag. It stops short of saying what a row looks like structurally beyond field naming, so it is solid rather than exceptional.

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

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

Three sentences, front-loaded with purpose, then a dense field/cohort inventory, then paging and alternatives. Almost no filler, though the row-field enumeration is packed enough to be slightly heavy on first read.

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 return-shape burden and does reasonably: it enumerates row fields, explains cohort categories, describes the topics list and its truncation flag, and details paging. The main residual gap is the exact envelope/pagination field naming (next_cursor vs the schema's cursor), which an agent narrows from context.

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 all six parameters are documented in the schema and the baseline is 3. The description does add meaning for cohort (core scored vs comparison naming a competitor, reported separately) and for active/audit status, but it does not explain the filters' interaction or the valid range of limit beyond what the schema says.

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 ("List the prompts the project tracks") and immediately frames the scope as enumeration, not search or results. It names the distinguishing siblings (search, read_visibility_results) so the agent can tell it apart without opening a 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?

States when to reach for it ("before reading results or changing prompts") and explicitly routes the two most likely competing intents elsewhere: wording lookup goes to search, per-prompt engine answers go to read_visibility_results with the prompt_id. Downstream tools that consume the returned ids are also named.

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, non-destructive, closed-world, so the description correctly spends its words elsewhere: the strict window-match requirement, the specific unavailability error code and the warning that it is "not zero", pagination via next_cursor, and the explicit absence of country/device/search-type breakdowns. These are failure modes and data-shape constraints an agent cannot infer from the 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?

Structure is strong: purpose first, then routing to alternatives, then the window constraint and error, then row shape and pagination. It is dense and slightly run-on in places (the error-code sentence), but essentially every sentence carries new information, with no 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?

There is no output schema, so the description carries the burden of describing the return shape, and it does: row granularity, the fields returned, and how to page. Combined with the window prerequisite and the disjoint-filters note ("All filters combine" in the schema), an agent has everything needed to call this 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 a baseline of 3 applies, but the description adds real meaning: it explains that rows are query/page/day and what site_url_id and resolution_outcome mean in the returned data, which illuminates the corresponding filters (site_url_id, resolution_outcome) beyond their schema text. It does not add syntax detail for query, limit or cursor beyond what the schema already says.

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 verb and resource ("Read the Search Console queries ... matched to pages CiteLadder crawled") and states the scope (one saved window, per page/day rows). It also explicitly differentiates from read_performance (totals/trends) and read_demand (search signals), so an agent can separate it from siblings without opening a 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 two concrete use cases (which queries a page ranks for; which page answers a query) and names the alternatives with the condition that selects them: read_performance for totals and trends, read_demand for signals in the same window. It also states a hard pre-condition (the window must exactly match a saved one, obtained from read_demand) and the consequence of violating 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 establish the safe read-only/idempotent profile, but the description goes well beyond them: it discloses pagination (50 default, next_cursor with the same sort), staleness ('rows are as saved at research time and are never refreshed'), and a substantive correctness warning that referring-domain/page totals are provider aggregates and must not be reported as a link list. It also notes cross-project datasets are refused.

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 routing lead, and the caveats (aggregate totals, staleness) follow in a logical order. It is a dense paragraph with several clauses, but each sentence carries distinct, non-redundant information, so little is wasted.

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 conveys the return shape (dataset metadata plus a page of rows, each with a citeladder:// id for fetch), the pagination contract, and the key semantic caveats. Nothing an agent needs to call and 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?

Schema coverage is 100%, so parameters are already documented and a 3 would be the floor. The description adds value above the schema by specifying the default page size (50) and that subsequent pages share the same sort, details the schema's 'default page size' and cursor fields leave 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?

States a specific verb and resource ('Read the rows of one saved keyword or backlink research dataset') and pins its place in the family by naming read_search_intelligence as the source of the id. An agent can distinguish it from read_search_intelligence and read_query_evidence 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?

Explicitly routes the agent: use read_search_intelligence to choose the dataset, this tool to read its rows, and read_query_evidence for the project's own Search Console queries. The prerequisite ('after read_search_intelligence has named it') is stated, not inferred.

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 genuinely useful context beyond them: the field-level shape of each dataset (id, kind, target domain, market, status, aggregate-vs-individual totals) and the 'unavailable means no research yet' semantic. It does not mention pagination, rate limits, or auth requirements, so it falls short of 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?

Front-loaded with the core purpose, followed by routing rules, then edge-case semantics. The middle sentence enumerating returned fields is long but earns its place given 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 carries the return-value burden and does so by naming the dataset fields and the project-level extras (owned targets, tracked competitors, latest run). Combined with the routing guidance, an agent has nearly everything needed; only pagination/size expectations are unaddressed.

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?

Only one parameter with 100% schema description coverage, and the schema ties it to list_projects' output. The description adds no further syntax or format meaning for project_id, so the baseline of 3 for schema-covered params 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 ('List') and a precise resource ('keyword, competitor and backlink research datasets saved for this project'), and immediately distinguishes itself from read_search_dataset ('It lists datasets only') and read_query_evidence. An agent can route between these three 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?

Explicit when-to-use and when-not-to: pass a dataset id to read_search_dataset for rows, use read_query_evidence for Search Console queries, and 'this tool never starts research, which happens in CiteLadder'. It also explains the 'unavailable with no datasets' status as a signal that no research was run yet.

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 readOnly/idempotent/non-destructive, and the description adds substantive behavior: only non-branded, question-like searches are returned, seeds are never copied into prompts, no volume/impression metrics exist, and 'unavailable no_search_data' signals no connected source. That last point is a genuinely useful error-state disclosure; only pagination/limits are missing.

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, then filtering, then the downstream handoff — a sensible order. It is dense but nearly every clause carries information; the 'never present a query as AI prompt volume' warning earns its place as a misuse guard.

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 compensates by naming the returned fields, the filtering rule, the empty/error state, and the downstream consumer. Nothing essential to correct invocation appears to be 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% for the single project_id parameter, so the schema does the work and the baseline is 3. The description never explains project_id itself, and the mention of seed_source/seed_query_ids refers to generate_prompts' parameters rather than this tool's input, which could momentarily confuse an agent about this tool's signature.

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 searches a prompt generation run could ground its wording on') and names the two data sources (search_console, search_intelligence), which distinguishes it from siblings like read_search_dataset and read_query_evidence. It also enumerates the returned fields (id, text, topic), so an agent knows exactly what it gets.

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?

Clearly frames the tool as the grounding step that feeds generate_prompts, and explicitly tells the agent to pass results as seed_source and seed_query_ids. It does not compare itself against the other read_* search siblings, so the alternative-selection guidance is only partial.

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 a key behavioral boundary ('this tool never starts one' – i.e., it never triggers a crawl) and defines the error sentinel 'no_site_snapshot'. It also spells out the exact return payload, which the annotations alone do not 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?

Two sentences, both dense and front-loaded: the first delivers the payload contents, the second handles routing and the error case. There is no filler or repeated structured 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?

There is no output schema, so the description carries the burden of describing returns, and it does so thoroughly (score categories, measurement state, page counts, top-10 issue structure). For a two-parameter read tool with safety annotations, nothing material 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% and both parameters are fully documented in the schema, including the 'omit for latest crawl' default and the crawl-id alias. The description's phrase 'or a chosen snapshot' restates that without adding syntax or format detail, 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?

The description uses a specific verb and resource ('Read the Site Health summary of the latest crawl, or a chosen snapshot') and enumerates the returned fields (fundamentals/AI-readiness scores, measurement state, page counts, top 10 issues with rule_id, severity, remediation). It also differentiates itself from siblings by naming read_site_pages, read_ai_crawlability, and render_site_health with their distinct roles.

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

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

It explicitly states the usage context ('latest crawl, or a chosen snapshot'), gives a negative case ('unavailable no_site_snapshot means no crawl was analyzed yet'), and routes the agent to alternatives: read_site_pages with a rule_id for affected pages, read_ai_crawlability for robots access, render_site_health for the interactive view.

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 read-only, idempotent, non-destructive, closed-world call, but the description adds genuinely new behavioral facts: batching up to 10 ids yields smaller neighbor samples and anchor diagnostics 'counted by kind', the missing_site_url_ids return field flags pages with no link metrics, and 'unavailable no_site_crawl' reports a missing crawl. Pagination via next_cursor is also disclosed. 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 return payload is front-loaded and the routing and batching/pagination rules follow in a logical order. The dense enumeration of returned metrics is long but each clause carries distinct information; a light restructure into separate sentences would improve scanability without cutting content.

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 carry the return contract, and it does: metric inventory, sampling behavior, missing-id reporting, pagination, and an error code. For a five-parameter read tool with full annotation coverage, an agent has everything needed to call it correctly on the first attempt.

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 cannot: it explains that site_url_ids come from read_site_pages, that batching changes the response shape (smaller samples), and that omitting ids pages through every page. It also describes cursor semantics ('pass next_cursor for more') despite the schema naming the field 'cursor', which is a small naming mismatch rather than a fatal 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 names a specific verb and resource ('Read the internal links of crawled pages') and then enumerates exactly what each row contains: inbound/outbound counts overall and in main content, nofollow inbound, click depth, bounded neighbor samples with anchors, and anchor diagnostics. It also explicitly separates itself from read_site_pages ('for page scores and issues'), so an agent can choose between them 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 gives a concrete motivating use case ('find orphaned or buried pages') and routes to the right alternatives: read_site_pages for page scores and issues, read_site_health as the source of crawl_id. What is missing is an explicit when-not-to-use beyond those sibling pointers, so it falls just short of the full when/when-not/alternatives bar.

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, non-destructive, closed-world), and the description adds genuinely useful behavior: output is metadata only, and the non-obvious rule that a site-level architecture issue is recorded once on the homepage with rule_evidence naming the affected pages. It does not spell out default page size or how cursor progression terminates, leaving modest gaps in the read loop.

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 return payload, then the three filtering paths, then the two disambiguating pointers — a deliberate and readable order with no filler. It is dense (one long multi-clause sentence in the middle) and slightly hard to scan, but every clause carries 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 an 8-parameter filtered-list tool with no output schema, the description carries the return burden well by enumerating fields and explaining rule_evidence's indirect semantics. The only shortfall is paging mechanics, which the schema documents but the description never reinforces.

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 3 is the baseline, but the description adds meaning beyond the schema: rule_id provenance from read_site_health top_issues or an issue group, and what rule_evidence contains per page. It does not restate the url normalization or crawl_id defaulting rules, which the schema already handles.

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 ("Pages from a crawl, paged") and immediately enumerates the returned fields, so the agent knows exactly what object it gets. It draws explicit boundaries against read_page_text ("metadata, not page copy") and read_site_health (totals), making it distinguishable from siblings 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 per-parameter routing rules: pass url to find a page by address, rule_id (sourced from read_site_health top_issues or an issue group) to list exactly the affected pages, page_kind or status to find pages by type or state. It also names the two alternatives and when to prefer them, leaving no inference required.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real context beyond that: result caps (50 prompts, 12 brands), the aggregation semantics of omitting audit_id, and the url_not_cited_in_selection outcome. It stops short of explaining truncation/sorting behavior for the capped lists.

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 verb and purpose, then two short sentences for scoping and error handling. The first sentence is dense with a long enumeration of return fields, 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?

There is no output schema, so the description carries the full burden of describing the return payload, and it does so concretely, including the caps on the prompts and brands lists. Combined with the schema's parameter docs and the annotations' safety profile, an agent has what it needs to call this 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: omitting audit_id pools every run rather than defaulting to the latest, and the URL must match the cited URL exactly with a named failure mode. The cohort, engine and market_id semantics are largely left 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?

States a specific verb+resource ("Read one cited page in depth") and enumerates the exact payload: retrieval/citation frequency, first/last seen, citing engines and models, prompts (up to 50), brands (up to 12), and on-page content. It is clearly distinguishable from the discovery sibling read_visibility_sources, which it names as the upstream step.

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 prerequisite and trigger ("after read_visibility_sources or an answer names it") and clarifies the audit_id omission case (every run in the market vs latest). It does not state when a different read tool (e.g. read_ai_traffic_url, read_query_evidence) would be the better choice, so it stops short of full alternative 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 declare readOnly/idempotent/non-destructive, so the bar is lower, but the description still adds real behavioral context: default selection of the latest completed run, the market-never-pooled measurement rule, and the meaning of two specific error states (unavailable no_completed_run vs metrics_pending) with guidance to retry rather than misreport. It stops short of defining how the score or share of voice are computed, which is the only 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?

Front-loaded with what is returned, then defaults, then error semantics, then sibling routing — a sensible ordering with no filler sentences. It is dense and long-ish for a single paragraph, but each clause carries distinct information; a slightly tighter split would aid scanning.

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 six-parameter read with no output schema, the description carries return-value burden well by enumerating the headline metrics and per-engine breakdown, plus default and error-state behavior. It does not describe the response structure or field names, which leaves a small gap an agent must 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 coverage is 100%, so baseline is 3; the description earns an extra point by stating the operational intent behind baseline_id (compare two runs) and market_id (switch market; markets never pooled), which the schema documents only as types. It adds no commentary on cohort or engine, which the schema already explains.

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 ("Read the headline AI visibility of one run") and then enumerates the exact payload: mention/citation rates, visibility score, competitor rankings with four named sub-metrics, per-engine breakdown, and run status. The scope (one run, one market) is explicit, so an agent can distinguish it from read_visibility_trends or read_visibility_results without opening a 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?

Explicitly names the defaults (latest completed run, default market), the two overriding conditions (pass baseline_id to compare two runs, pass market_id for another market), a hard constraint (never pool markets), and three named alternatives with their selection conditions (trends for change over time, results for answers, sources for citations). Nothing is left 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 read-only, idempotent, closed-world, non-destructive, so the safety profile is covered; the description adds behavior the annotations cannot express — results are paginated via next_cursor, and the default cohort silently limits rows to core prompts. Those are the two traits most likely to cause an agent to misread an empty or short result set, and both are disclosed.

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 what the tool returns, then the required-input warning, then pagination, then scoping defaults, then filter behavior, then sibling routing. Every sentence carries a distinct fact and none repeats the schema verbatim.

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?

Nine parameters and no output schema, so the description carries the return-shape burden — and it does, enumerating prompt text, engine, model, repetition, web-search flag, brands with first position, citations with URL/domain/own-vs-competitor, and a citeladder:// id for fetch. Combined with the pagination and cohort notes, an agent has everything needed to call and interpret it.

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 each parameter and a baseline 3 would apply. The description goes beyond it by stating that filters (prompt_id, domain, url, engine) combine — an interaction the schema does not express — and by tying audit_id to its source in read_visibility_overview; the cursor/next_cursor round-trip is described though the parameter is named 'cursor'.

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 — read the answers engines gave in one run — and immediately names the two siblings it is not (read_visibility_overview for rates, read_visibility_sources for citation totals). An agent can distinguish it from the other visibility tools 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 rules: use overview for rates, sources for citation totals, this tool for per-answer text. It also states the prerequisite (audit_id comes from read_visibility_overview) and the default scoping caveat (only core prompts unless cohort is comparison or all), which is exactly the kind of when-to-use guidance that prevents wrong calls.

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, so the description's added value is in return shape and pagination: row fields (answers, prompts, citation share and rate, ownership, category), page-level brands and Action flag, and next_cursor paging. With no output schema this is genuinely useful context. It stops short of any rate-limit, ordering, or freshness detail beyond 'latest run', so it is good but not exhaustive.

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 ranking, then row contents, then defaults, then paging, then level semantics, then alternatives. Every sentence carries information. It is one dense block with an awkward clause ('unavailable no_completed_run means none has finished') that costs a little 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?

No output schema exists, and the description compensates by enumerating the row fields and the page-specific extras. Pagination, default run selection, error signal, level behavior, and sibling alternatives are all covered, leaving nothing an agent needs to call 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. The description still adds semantics the schema does not spell out — notably that passing a domain with level url lists that domain's pages — and reinforces the default-to-latest-run behavior for audit_id. cohort and engine are left entirely to the schema, which is acceptable given full coverage.

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 — 'Rank the domains or pages AI answers cited in one run' — plus the goal ('find the sources worth earning a place on'). This separates it cleanly from read_source_url (one page in depth) and read_visibility_results (the answers themselves).

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?

Explicit routing: read_source_url for a single page, read_visibility_results for citing answers, and a rule for domain-level vs url-level or domain-filtered listings. It also states the default run and what no_completed_run means, so an agent knows when to switch runs rather than retry.

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), but the description adds real behavioral context on top: the 100-point truncation cap, the semantics of comparison_key (points with different keys are not comparable), that gaps mean missing runs rather than zero, and the unavailable/no_measured_runs error meaning. These are the operational details an agent needs to interpret results correctly.

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 core action and window constraint lead, followed by point contents, caveats, and the sibling routing. The enumeration of point fields is slightly list-heavy, but every sentence carries information an agent needs, with no 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 no output schema, the description carries the burden of describing returns, and it does: point fields, the 100-point cap, comparison_key incomparability, gap semantics, and the no_measured_runs error. Nothing material for correct invocation or interpretation appears to be missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it frames granularity as the shape of a point (per run vs per day/week/month), ties the 366-day cap to the from_at/to_at pair, and explains that comparison_key distinctions make points non-comparable, which is not evident from the field name alone.

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+resource ('Read how visibility changed over an explicit window') with the scope constraint (at most 366 days) baked in. It explicitly differentiates itself from read_visibility_overview and read_visibility_results, so an agent can route 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?

Names the alternative tool and the conditions that select it: read_visibility_overview for one run in depth, or with baseline_id to compare exactly two runs. The window and granularity constraints further scope when this tool applies, leaving little 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 flag destructiveHint=true and idempotentHint=false, but the description adds materially more: recorded answers survive the removal, the change applies immediately with no confirmation step, it cannot be undone, and re-adding is lossy for aliases/domains. That is exactly the behavioral context an agent needs before an irreversible write.

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

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

Three sentences, zero filler, and the ordering is deliberate: action and scope first, what is preserved second, irreversibility and the recovery path last. Every clause carries decision-relevant 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 two-parameter destructive write with no output schema, the description covers what is removed, what is retained, the immediacy and irreversibility of the effect, and how to reverse it. Nothing an agent needs to call it safely 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 baseline is 3; the description goes slightly beyond by telling the agent where to source a valid competitor name (get_project_business_context), which the schema's 'tracked competitor name' wording does not. It adds no format detail beyond that.

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 ('stop tracking') and resource ('one competitor'), scoped to a single entity by name. It is immediately distinguishable from add_competitor and from read_* siblings that surface visibility data.

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?

Tells the agent where the valid name comes from ('as get_project_business_context lists it') and names the reversing alternative (add_competitor) along with the caveat that aliases and domains must be re-supplied. Both the when and the undo path 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?

Goes well beyond annotations (which only say non-read-only, idempotent, non-destructive): it discloses that data is preserved ("prompts and past results stay under it"), that it executes immediately, that it returns the new name, and the two refusal conditions (name collision, foreign topic_id). This is exactly the mutation-safety context an agent needs.

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 the action, then the sibling routing, then execution/failure behavior. No filler; every clause 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?

No output schema exists, and the description supplies the return value ("returns the new name") plus failure modes. For a 3-required-param mutation tool, an agent has everything needed to decide, call, 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 the baseline is 3. The description adds a real constraint not obvious from the schema: topic_id must belong to the given project, and name must be project-unique or the call is refused — meaningful semantics beyond field types.

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: "Rename one topic," with an explicit scope of exactly one topic. It distinguishes itself from the two nearest siblings (delete_topic, create_topic) by naming them and stating the condition that selects this 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?

Explicit alternative routing: "prefer this to delete_topic and create_topic when only the name is wrong." It also states a precondition ("after the user agrees"), so the agent knows a confirmation gate applies before calling.

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 establish that the tool is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context by explaining that it renders an interactive view for the user rather than returning data for reasoning, and that it only applies in clients that display apps. It does not describe fallback behavior in non-display clients, but the annotations carry the safety profile.

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 zero waste. The primary action and scope are front-loaded, followed by the alternative tool routing. Every sentence earns its place.

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

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

For a render tool with no output schema, the description is complete enough: it names the view's contents, the snapshot scoping behavior, and the client restriction. Safety and idempotence are covered by annotations, leaving no material gaps for correct invocation.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the snapshot can be the latest or a chosen one, but adds little syntax or meaning beyond the structured input schema. This meets the baseline for high schema coverage.

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

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

The description states a specific verb and resource: it shows an interactive Site Health view with scores, coverage, and top issues. It also scopes the operation to the latest or a chosen snapshot and distinguishes itself from read_site_health, so an agent can tell exactly what this tool does.

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

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

It explicitly names the alternative read_site_health and the condition for choosing it: when the agent wants to reason over the data itself. It also clarifies that this tool is for clients that display apps, giving clear context for when to use 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/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: this tool renders UI and only functions in app-capable clients, and it is the display counterpart to the read_* tools. It stops short of describing what each view renders or any failure 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, zero filler, and the core action plus routing guidance are front-loaded. Every clause earns its place.

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

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

For a 15-parameter render tool with no output schema, the description covers the essentials: it works only in app-capable clients, which views exist, and when to prefer the read_* alternatives. What each view actually shows is left implicit, which is the only meaningful 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 100%, so the schema already documents all 15 parameters including the per-view applicability notes. The description's phrase 'trends over a window, or cited sources for one run' only loosely maps to view/from_at/to_at/audit_id and adds no format or constraint detail beyond the schema. 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 a specific verb and resource ('Show the user an interactive visibility view') and enumerates the three variants (overview, trends, cited sources). It explicitly distinguishes itself from the read_* siblings by framing this as a display action rather than a data-retrieval one.

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 when-to-use condition ('in clients that display apps') and names the three alternatives ('use read_visibility_overview, read_visibility_trends or read_visibility_sources') with the selecting rationale ('To reason over the numbers yourself'). An agent can route correctly without opening any schema.

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, destructiveHint=false and openWorldHint=false, so safety and scope are covered structurally. The description adds that results carry ids usable with fetch, but says nothing about ranking, match type, truncation, or what an empty result means; with annotations carrying the rest, a 3 is appropriate.

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

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

Two tight sentences with zero filler; the core capability comes first and the id/fetch handoff is the second beat. Every clause 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?

With no output schema, the description usefully discloses the shape of results (matching records with ids) and the follow-up step. It leaves minor gaps around result ranking and the empty-result case, but for a simple three-parameter read tool it is nearly 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%, so limit, query, and project_id are fully documented in the schema itself. The description adds no syntax, matching behavior, or scoping nuance beyond what the schema already says, 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?

States a specific verb (find) plus the exact resource set (projects, active Actions, prompts) and the condition (when you do not know where a record is). It also differentiates itself from the sibling 'fetch' by explaining the id handoff, so an agent can route correctly 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 clear usage context ('when you do not know where a record is') and names the alternative path ('pass one to fetch for the full record'), which is effectively a when-to-use-this vs. when-to-use-fetch rule. It stops short of stating exclusions, e.g. that it should not be used when the id is already known or that it is not a substitute for the read_* analytic 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 already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Runs at once' signals synchronous, immediate effect with no preview/async job, and 'one Action' scopes the mutation to a single record rather than a bulk operation.

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 the primary action and its inverse, followed by timing behavior and the disambiguation pointer. Every sentence earns its place with no 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?

For a three-parameter, no-output-schema status toggle, the description covers what changes, immediacy of effect, and the main routing decision. It does not mention error/failure behavior (e.g., invalid action_id, unknown project), which is a minor gap given the tool's simplicity.

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 schema already explains the status enum values and where action_id/project_id come from. The description's 'one Action' phrasing reinforces that action_id is singular, but adds no new syntax or format guidance beyond the schema — 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?

The description states a specific verb pair (dismiss / reopen) applied to a specific resource (one Action), and explicitly names the sibling tool that handles the adjacent case ('To record that the work was done, use prepare_declare_implemented instead'). An agent can distinguish this from read_actions and prepare_declare_implemented 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?

It names the two conditions for use (dismiss an Action the user does not want to act on; reopen a dismissed one) and gives an explicit when-not/alternative for the 'work completed' path via prepare_declare_implemented. Nothing about tool selection is left 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 cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds non-obvious behavior beyond them: it executes immediately, returns the new wording, and — importantly — earlier measurements retain the old wording so pre/post-edit results are not comparable. It also discloses a validation failure mode. No contradiction with the 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?

Dense but front-loaded: the action, the precondition, and the return value come first, and the caveat and sibling routing follow. No sentence is filler — each one either sets the trigger, warns about comparability, or routes to an alternative.

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 3-parameter mutation with no output schema, the description covers what the tool does, when it fires, what it returns, what is preserved (historical measurements), and how to reach adjacent operations. Nothing an agent needs to call it 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 description coverage is 100%, so baseline is 3; the description adds real value by stating the cross-parameter constraint that prompt_id must belong to the given project, plus the intent of 'text'. It does not add format/syntax detail beyond the schema, so it lands just above 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?

States a specific verb and resource ('Replace the wording of one tracked prompt') with concrete motivating examples (fix a typo, make it read like a buyer's question). It also distinguishes itself from the prepare_* siblings by stating it 'Runs at once', so an agent can tell it apart from the prepare/confirm flow.

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 precondition ('after the user agrees'), the purpose of the edit, and explicit routing to alternatives: archiving goes to prepare_archive_prompts, adding goes to prepare_add_prompts. It also names a rejection condition (prompt_id not in this project), which is exactly the when-not guidance an agent needs.

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