CiteLadder

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description adds that the write is immediate/synchronous, which is genuinely extra context, but it omits what happens on duplicate competitors (despite idempotent=false) and how aliases/domains affect tracking.

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, front-loaded sentences with no filler; the action and its immediacy lead. It is terse to the point of under-informing rather than wasting words.

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 4-parameter mutation with no output schema and 0% schema description coverage, the description is too thin: it explains neither the roles of aliases/domains/project_id nor duplicate or error behavior. It leaves an agent under-equipped 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 description coverage is 0% across 4 parameters, so the description must compensate, and it largely does not: aliases, domains, and project_id get no mention at all. Only "one more competitor" faintly implies a single name per call.

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

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

States a concrete verb (track) and resource (competitor) in a specific domain (AI answers), so an agent immediately knows it mutates the tracked-competitor set. It does not explicitly distinguish itself from siblings, though no sibling covers competitor tracking.

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?

"Runs at once" implicitly contrasts with the prepare_*/confirm_change workflow siblings, hinting that this tool executes immediately without a confirmation step. However, it never names an alternative or states prerequisites/exclusions explicitly.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real behavioral detail beyond them: the stop is immediate ('runs at once'), irreversible ('cannot be undone'), and preserves partial results. It does not mention permission requirements, which is a minor gap.

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

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

Two tight sentences with no filler; the core action leads and the irreversibility warning follows immediately. 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 notes that prior results are retained, which is the key post-call expectation for a destructive cancel. It could go slightly further on what the caller receives back or whether a completed audit can be targeted.

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

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

Schema description coverage is 0% for two required UUID parameters, so the description carries the full burden here, yet it says nothing about project_id or audit_id. Their formats and roles must be inferred entirely from the field names.

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 ('Stop ... audit') and narrows the scope to 'queued or running', so the agent knows exactly which audits this applies to. It is naturally distinguished from the sibling prepare_launch_audit/prepare_schedule tools without ambiguity.

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

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

Usage is implied by the state restriction ('queued or running audit'), which tells the agent when the call is valid. However, there is no explicit when-not guidance or pointer to an alternative (e.g., how to restart or fully remove an audit), leaving some routing 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 destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the mutation profile is covered. The description adds genuine value beyond that: the token is single-use ('works once') and expires in ten minutes, which the annotations 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?

Three tight sentences, front-loaded with purpose, then the precondition, then the token constraint. No wasted text.

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

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

For a simple one-parameter commit tool with safety annotations already present and no output schema required, the description covers purpose, the critical when-to-call gate, and token lifecycle. Only the token's origin is left implicit.

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

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

Schema coverage is 0%, so the description must carry the one parameter. It does add meaningful token semantics (single-use, 10-minute lifetime), but never states where the token comes from (presumably the prepare tool's output) or its format, leaving part of the semantics to inference.

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 action (make a change that a prepare tool previewed) and ties it to the prepare_* sibling family, so an agent can place it in the prepare/confirm workflow. The resource itself is generic (whatever was prepared), which is inherent to the design, but the pattern is clear.

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?

'Call only after the user explicitly agreed to that preview in this conversation' gives an explicit precondition and effectively an exclusion (do not call before agreement). It doesn't name a specific prepare sibling, but the prepare family reference is sufficient context.

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 non-read-only, non-destructive, non-idempotent, closed-world behavior, so the safety profile is covered. 'Runs at once' adds a genuine behavioral fact (synchronous, no async polling), but nothing is said about duplicate names, permissions, or side effects on existing prompts.

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 with no filler, and the core action is front-loaded. 'Runs at once' is terse to the point of being slightly cryptic, which keeps it just below 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?

For a three-parameter mutation tool with no output schema, no parameter documentation, and only safety annotations, the description is too thin. An agent gets no information about return values, uniqueness constraints, or how the new topic relates to existing prompts.

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

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

Schema description coverage is 0% across three parameters, so the description carries the burden and does not meet it. It never mentions name, project_id, or description, leaving their meaning and constraints (UUID format, 255/1024 length limits) undocumented in 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 (add) plus resource (topic) and its purpose (grouping prompts under it), so an agent knows what gets created. It does not explicitly differentiate from the sibling rename_topic, which is the main clarity gap.

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

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

There is no when-to-use guidance, no prerequisites (e.g. that project_id must reference an existing project), and no mention of alternatives such as rename_topic. The phrase 'to group prompts under' only implies context rather than stating 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/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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds that sections is an optional narrowing filter over a default full read, which is useful behavior beyond the annotations, but says nothing about payload size, cost, or latency of the unfiltered 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?

Two sentences with the scoping behavior front-loaded and the section list packed into the second. The enum enumeration is long but informative rather than wasteful; no filler prose.

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 aggregate read with no output schema, the description identifies what each section contains well enough that an agent can decide what to request. It does not describe the response shape or nesting, but with a section list present the omission is minor.

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

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

Schema description coverage is 0%, so the description carries extra weight. It does explain the semantics of sections (opt-in narrowing, default reads everything) and restates the valid enum values, but adds nothing about project_id format or section interdependencies. Partial compensation for the coverage gap, so a mid score.

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 — a single aggregated overview of a project — and enumerates the content categories it returns (profile, competitors, prompts, visibility, actions, Site Health, connected data). An agent can differentiate it from the many atomic read_* siblings by its aggregate nature, though it never explicitly says it supersedes them.

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

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

"Pass sections to read fewer" is a genuine usage hint about payload reduction, but there is no guidance on when to prefer this aggregate over the sibling read_site_health / read_visibility_overview / read_crawl_logs tools, nor any stated prerequisites or exclusions beyond the required project_id.

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 closed-world, so the safety profile is fully covered. The description adds the 'can read' authorization scope, which is useful, but says nothing about result volume, truncation, or how paging behaves despite the cursor parameter.

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

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

Two short sentences, zero filler, with the entry-point guidance front-loaded immediately after the purpose statement.

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

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

For a two-parameter, no-output-schema list tool with full annotation coverage, the description is nearly sufficient; an agent knows what it gets and when to call it. The one real gap is paging behavior, which the schema only hints at via `cursor`.

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 only 50%: `cursor` is documented but `limit` has no description and no default, and the description says nothing about paging size or iteration. For a list tool where pagination governs correct usage, the description should compensate and does not.

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 projects) and adds a real scope qualifier: only projects this connection can read. It does not name a sibling alternative, but among ~45 mostly read_*/prepare_* siblings, 'list the projects' is unambiguous about what resource is returned.

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?

'Start here when no project is known' gives an explicit trigger context, which is genuinely useful for a discovery tool in a large sibling set. It stops short of saying when not to use it or naming a follow-up tool once a project is known.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description is free to add the harder-to-infer details. It does not, however, say what side effect 'open' has on the client or what the caller gets back, which is the one behavior an agent most needs here.

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

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

A single short sentence with the action front-loaded and no padding. It is efficient, though the brevity is partly the source of the ambiguity elsewhere.

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 parameters and no output schema, the definition is structurally simple, but a tool whose entire job is a UI navigation action should say what invoking it produces or requires of the client. The gap is small but real for an agent deciding whether to call 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?

The tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to disambiguate. The baseline for a zero-parameter tool 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 pairs a specific action verb ('Open') with a concrete resource ('the CiteLadder project picker'), and it is the only open_* tool among siblings that are otherwise reads and prepares, so an agent can place it. It stops short of a 5 because it never says what 'open' means for an MCP caller (a URL, a client-side UI launch, a rendered resource) and does not explicitly contrast itself with the many read_* alternatives.

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

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

There is no when-to-use or when-not-to-use guidance. The agent must infer that the picker is for letting a user select among projects, and nothing routes it to or away from list_projects, get_project_business_context, or the read_* family.

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; the description adds real behavioral value by clarifying that no state changes until confirm_change is called and that confirmed prompts are measured from the next audit. This resolves the ambiguity left by readOnlyHint=false for a 'prepare' tool. It does not cover re-invocation behavior, despite idempotentHint=false.

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 preview behavior and the no-change guarantee are front-loaded, and the audit-timing detail is a compact trailing 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?

With no output schema, the description helpfully characterizes the preview result (which can be added, which are dropped and why, slots after) and the confirmation flow. The remaining gap is the undocumented parameters, which the schema does not describe either.

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

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

Schema description coverage is 0%, so the description must carry the load. It only constrains the prompts array size (1–50) and mentions the prompt set target; project_id, prompt_set_id, and the nested text/cohort/intent/topic_id fields are left entirely to the schema. Partial compensation, not full.

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 adding), resource (prompts into a prompt set), and scope (1–50). It is clearly distinguishable from the sibling prepare_archive_prompts and from read_prompt_portfolio.

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 frames this as a preview step and names the follow-up tool (confirm_change) plus the condition that gates it ("until the user agrees"). It does not spell out when *not* to use it or what to do if items are dropped, but the workflow context 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 declare readOnlyHint=false and destructiveHint=true, but the description states 'Nothing changes until the user agrees and you call confirm_change,' which implies the tool itself is non-destructive and read-only. This directly contradicts the annotations, so per the scoring rules it is scored 1.

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

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

Two sentences, front-loaded with the core action and effect, followed by the crucial workflow constraint. No filler or redundancy; 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 two-parameter tool with no output schema and contradictory annotations, the description is too thin. It omits parameter semantics and does not clarify what the preview returns (e.g., a token needed by confirm_change) or how the two calls relate beyond the user-agreement condition.

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

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

Schema description coverage is 0%, and the description does not explain the meaning, format, or role of project_id or prompt_ids. It only alludes to 'tracked prompts' without mapping to the parameters. The schema provides types and formats but no semantic descriptions, so the description fails to compensate.

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

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

States a specific verb and resource: preview archiving tracked prompts. It also clarifies the scope (future audits stop measuring them; past results stay) and distinguishes this tool from confirm_change, which actually applies the change. An agent can immediately tell what this tool does and how it differs from its sibling.

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 follow-up tool (confirm_change) and the precondition for actually applying changes (user agrees). This routes the agent through the intended two-step workflow without ambiguity. No exclusions are stated, but the alternative for committing the change is clearly identified.

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

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description adds the crucial behavioral fact that nothing is mutated yet and that a follow-up confirm_change is required. It doesn't mention idempotency or re-running behavior, which is relevant given idempotentHint=false.

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, front-loaded with the preview semantics and closing with the commit condition. 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?

The preview/confirm workflow is fully conveyed and no output schema exists to explain, but with three parameters at 0% schema coverage and no annotation detail beyond safety hints, the definition leaves parameter usage entirely opaque. Adequate for the workflow, incomplete for 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 0% and the description says nothing about any of the three parameters. In particular declared_implemented_at (an optional date-time) is completely undocumented in both schema and description, leaving its format and purpose unexplained. No compensation for the coverage 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?

States a specific verb and resource ('declaring that the work of an open Action is done') plus the distinguishing trait that this is only a preview. It also names the sibling confirm_change that actually commits the change, so an agent can tell it apart from a direct write.

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 the workflow context clearly: use this first, then get user agreement, then call confirm_change. It doesn't explicitly say when NOT to use it (e.g. vs update_action_status or read_actions) and doesn't state prerequisites such as the Action needing to be open, but the two-step 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 mark this non-read-only and non-idempotent, and the description earns its keep by resolving the apparent tension: a 'preview' that nonetheless mutates nothing until confirm_change is called. That two-phase, no-side-effect-until-confirmed behavior is real context beyond the annotation flags, though permissions, rate limits, and what the preview returns go unstated.

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

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

Four sentences, front-loaded with the core action and closed with the critical safety constraint. The clause 'with the prompt runs it can spend and its maximum provider attempts' is somewhat convoluted but stays within reasonable length.

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 preview tool with no output schema and four optional parameters, the description covers the essential flow and the confirm gate. It falls short on what the preview actually returns (runs, spend estimate) and leaves several optional parameters unexplained, but nothing critical to a correct two-step 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 0%, so the description carries the param burden, yet it explains only market_ids ('null is the default market') and max_attempts ('cap the attempts'). prompt_ids vs prompt_set_id is loosely implied by 'a prompt set (or chosen prompts),' while repetitions, engines and project_id remain undocumented—a significant gap at seven parameters even allowing for self-evident enums.

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 and resource: 'Preview launching an audit of a prompt set (or chosen prompts) on the given engines.' It also positions itself against the sibling confirm_change, so the agent can tell the two-step pair apart without inspecting 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 describes the workflow: this is a preview, 'Nothing runs until the user agrees and you call confirm_change.' It also routes per-market behavior to market_ids and hints the ids come 'from the project context.' No explicit when-not-to-use case, but the sequencing with confirm_change covers the main decision.

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

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

Annotations already declare a non-read-only, non-destructive, non-idempotent mutation, but the description adds genuinely useful context beyond them: the operation is a preview that changes nothing until confirm_change is called, and 'Each recorded answer spends one prompt run' discloses a cost/billing side effect. This is meaningful behavioral disclosure, though it stops short of permissions or return format.

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

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

Three tight sentences with no filler, front-loading the purpose before the market_ids mechanics and the confirm-change caveat. Efficient and well ordered.

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 mutation tool with no output schema, the description covers the essential preview/confirm behavior and market scoping but leaves most parameters undocumented. The workflow-level information is adequate, but the invocation details an agent needs for the six unexplained parameters are absent everywhere.

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

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

Schema description coverage is 0%, so the description must carry the full burden, but it only explains market_ids ('from the project context; null is the default market', one audit per market). The remaining eight parameters — cadence, engines, timezone, next_run_at, repetitions, interval_minutes, prompt_set_id — get no semantic clarification in either the schema or the description.

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

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

States a specific verb and resource: 'Preview a recurring audit schedule for a prompt set.' The word 'recurring' plus the confirm_change reference distinguishes it from the sibling prepare_launch_audit, though that contrast is implied rather than stated.

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 the two-step preview-then-confirm flow ('Nothing changes until the user agrees and you call confirm_change') and how market_ids drives scope, which is implied usage guidance. However, it never states when to choose this over the sibling prepare_launch_audit or any exclusion conditions.

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 safety profile is covered. The description adds genuine value by disclosing what each mode returns (status list vs. findings, remediation, measured outcome), but omits pagination/ordering behavior despite the limit and cursor parameters.

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 primary purpose is front-loaded and the mode switch is stated immediately after. 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?

With no output schema, the description carries the return-value burden and partially meets it by naming the payload of the single-Action mode. It is incomplete on the list mode's pagination and filtering semantics, which 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 description coverage is only 20% (only cursor is documented), so the description must compensate. It does explain action_id's effect, but says nothing about the status enum filter, the limit ceiling of 200, or whether project_id scopes the list, leaving most parameters unexplained.

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' + 'prioritized Actions to improve visibility') and clarifies the two modes (list vs. single via action_id). It is distinguishable from the write-side sibling update_action_status, though it does not name or contrast with any specific sibling.

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

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

It tells the agent that passing action_id returns a single detailed Action, which is implied usage guidance for that branch. However, there is no guidance on when to use the list form versus the single form, when to filter by status, or how pagination via cursor/limit should be driven.

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, so the safety profile is covered. The description adds two valuable non-obvious behaviors: non-ChatGPT engines return not_applicable (never zero, preventing misread as 'no ads'), and ads are paid placements to be reported separately from citations/sources. It doesn't cover paging limits or auth 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?

Front-loaded with the core noun phrase, then the payload list, then the engine caveat, then the reporting warning. Dense parenthetical enumerations cost some readability, but every sentence 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?

With no output schema, the description does the heavy lifting by describing the returned content in detail, and the engine not_applicable rule plus the 'never as citations' caveat cover the main interpretive risks. The remaining gap is parameter-level semantics for a 7-parameter tool.

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

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

Schema coverage is only 14% (just 'cursor'), yet the description never names or explains limit, cohort (core/comparison), engine, audit_id, or market_id. 'latest or a chosen run' and 'paged' faintly gesture at audit_id and cursor, but an agent gets no real semantics for 6 of 7 parameters.

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 ads in AI answers') and immediately enumerates the concrete payload: ad presence rate, advertiser share and first/last seen, brand ad share and best rank, text creatives, and surfacing prompts. This is clearly distinguishable from siblings like read_ai_shelf, read_ai_referrals, or read_visibility_sources.

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 real context for when it applies: 'for the latest or a chosen run' and the hard constraint that 'Only ChatGPT Search shows ads; other engines are not_applicable, never zero.' That engine rule is genuine when-to-use guidance. It stops short of naming an alternative sibling for non-ad questions.

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 safety is covered without the description. The description adds useful semantic context that the result reflects robots.txt permission rather than observed crawler visits, but says nothing about refresh timing, scope of crawlers covered, or auth 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?

Two short sentences with no padding, and the core capability is front-loaded ahead of the disambiguating clause. The telegraphic, verbless style is efficient but slightly reduces directness.

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 low-complexity read tool with annotations and no output schema, the definition covers the essential concept and crawl selection. It omits the result shape and project scoping, which a caller would otherwise have to discover, so it is adequate but not fully 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 coverage is 50%: crawl_id is documented in the schema and the description reinforces it ('latest or a chosen crawl'), but project_id is undocumented in both schema and description. The description adds marginal value over the schema without fully compensating for the coverage 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 states what the tool returns (whether robots.txt admits each AI crawler) and scopes it to the latest or a chosen crawl, so verb+resource+granularity are clear. The second clause 'Permission, not observed visits' cleanly distinguishes it from the AI traffic/referral siblings, though it isn't framed as an explicit verb like 'Returns'.

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 implies when the crawl_id matters ('for the latest or a chosen crawl') and hints at when to prefer this over observation-based tools via 'Permission, not observed visits'. However there is no explicit when-to-use/when-not phrasing or named alternative tool, leaving routing 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=true, idempotentHint=true, openWorldHint=false, so the safety profile is fully covered. The description's incremental contribution is that data originates from GA4, which is genuinely useful context, but it says nothing about auth needs, freshness, or sampling.

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

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

A single compact sentence with the resource front-loaded and no wasted words. It is efficient, though it trades away detail that would have earned its place given the 0% schema coverage.

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?

Without an output schema, the description usefully lists the return fields, which partly fills that gap. However, for a four-parameter tool at 0% coverage it omits all parameter guidance and any routing hints among the many sibling read_ai_* tools.

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

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

Schema description coverage is 0% and the description mentions no parameters at all, so it does not explain project_id, the range enum (30d/90d/1y), or the start_date/end_date pair. With four undocumented parameters, the description fails to compensate for the schema 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 resource (visits from AI assistants in GA4) and enumerates the returned data: sessions, traffic share, key events, landing pages. It is clear what the tool does, but it draws no boundary against the crowded cluster of siblings (read_ai_traffic_insights, read_ai_traffic_pages, read_ai_traffic_url), leaving 'referrals' vs 'traffic' ambiguous.

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

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

There is no when-to-use statement, no prerequisites, and no mention of alternatives. The only context is the parenthetical '(GA4)', which signals the data source but does not tell an agent when to pick this tool over the numerous other read_ai_* traffic 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine behavioral value beyond that: the output mode changes depending on whether a target is supplied (listing categories/products vs returning visibility, share of shelf, and shelf holder). It stops short of describing pagination or return shape.

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

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

Two short sentences, front-loaded with the domain concept before the mode behavior. No wasted words, though the terse phrasing makes the target/target_kind relationship slightly ambiguous.

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

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

With no output schema, the description does a fair job explaining the dual output modes. But for a 3-param tool with 0% schema coverage, it omits the required project_id and the distinction between target_id and target_kind, which an agent needs to invoke 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 0%, so the description must carry the load. It conveys the central role of 'target' (list mode vs detail mode) which maps to target_id, and 'categories and products' echoes the target_kind enum. But it never mentions project_id (the required param) or names target_id/target_kind explicitly, leaving meaningful gaps.

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 ('product recommendations in AI answers') with the read semantics carried by the name/title. It distinguishes itself reasonably from the many read_visibility_* siblings by focusing on product recommendations and shelf share. It doesn't explicitly name a sibling it is not, so it falls short of a 5.

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

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

It explains the two operating modes via the presence or absence of a target ('without a target... with one...'), which is useful invocation context. However, it gives no when-to-use vs alternatives guidance and never names which sibling to prefer for related questions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds one genuinely useful interpretive caveat, 'Co-occurrence, not cause,' warning the agent not to over-read correlations. It still says nothing about aggregation level, time-window behavior, or what a result set looks like.

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

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

Two terse fragments with no wasted words, and the data-domain scope is front-loaded ahead of the interpretation caveat. It is arguably over-terse for the amount of undocumented surface, but structurally it is clean.

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, four undocumented parameters, and a dense sibling set, the description should explain what an 'insight' returns and how to scope dates. Instead it offers only a scope fragment and a caveat, leaving the agent without enough to call the tool correctly or interpret its output.

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

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

Schema description coverage is 0%, so the description carries the full burden for four parameters (project_id, range, start_date, end_date), including a range enum of 30d/90d/1y. The description adds zero parameter meaning and never even mentions the date window or its relation to the range enum. Baseline does not apply here because coverage is far below 50%.

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

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

The description names the data domains (AI crawler, referral, citation) and the output shape (patterns), which suggests aggregation rather than the per-page/per-URL focus of siblings like read_ai_traffic_pages and read_ai_traffic_url. However, it contains no verb and never explicitly states it reads a report, so it largely echoes the name/title. Distinguishing it from the ~10 other read_ai_* siblings is left to inference.

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

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

No when-to-use guidance, no exclusions, and no mention of alternatives. The crowded read_ai_* sibling set (crawlability, referrals, shelf, traffic_pages, traffic_url) demands routing cues, and none are given. The agent must guess based on the name alone.

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 disclose the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds one genuinely useful behavioral note: the four metric groups have differing coverage, warning the agent that absent values are expected. It still omits pagination behavior despite a cursor parameter.

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

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

A single front-loaded sentence fragment ('Per page: ...') with no filler. It is efficient, though 'each with its own coverage' is imprecise enough to be near filler, which keeps it from 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?

For a 10-parameter read tool with no output schema and 0% schema coverage, the description does far too little. It never explains filtering/sorting/pagination or the shape of the per-page result, leaving the agent to infer from enums alone.

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

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

Schema description coverage is 0% across 10 parameters, including non-obvious ones like cursor, verification, resource_class, and folder. The description adds no meaning for any parameter, not even that sorting or date-range filtering is possible. The schema alone leaves most parameters opaque.

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 fragment states a resource (AI crawler requests, referral sessions, citations, Site Health findings broken down per page), which is a specific and non-tautological description. However, it never clarifies how it differs from close siblings like read_ai_traffic_url, read_ai_traffic_insights, or read_ai_referrals, and 'each with its own coverage' is vague. An agent can guess the purpose but not confidently distinguish it from neighbors.

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

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

There is no when-to-use guidance, no mention of prerequisites (it takes a required project_id), and no named alternative. The 'per page' grouping dimension is the only implied usage cue, which is weak given four sibling tools reporting overlapping AI traffic metrics.

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 closed-world, so the safety profile is fully covered by structured data. The description adds only that the output is a 'timeline ... for a range,' with no detail on pagination, granularity, or size limits. Adequate but thin on top of annotations.

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

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

Two tight sentences with the resource described first and the routing hint second. No filler, no repetition of the title, nothing that could be 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 and five parameters at 0% schema coverage, the description should explain what the timeline returns and how the date parameters interact. It does neither, leaving an agent unsure what the response contains and how to combine range with start_date/end_date.

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

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

Schema description coverage is 0%, so the description must carry all five parameters, yet it only glosses 'url' as 'one page on the project site' and vaguely references 'a range.' The relationship between range and start_date/end_date — clearly mutually related filters — is never explained, and project_id is untouched.

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

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

Names the specific resource and scope: the AI crawler and referral timeline for a single page on the project site, over a range. It clearly is not the pages-listing tool, since it points to read_ai_traffic_pages as the discovery step. The only slight weakness is the noun-phrase phrasing rather than a concrete verb, but the intent 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 sequencing rule: 'Use it after read_ai_traffic_pages names the page,' which tells the agent this is a drill-down reached from the pages tool. No negative guidance about when not to call it or how it differs from read_ai_referrals/read_ai_crawlability, which keeps it out of the 5 band.

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 behavior, so the safety profile is covered. The description adds a genuine scope constraint — the comparison draws only on pages 'CiteLadder has already read' — which tells the agent it does not fetch live content. It omits return format and pagination, but with annotations carrying the safety profile this is solid.

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 comparison scope is front-loaded and the action guidance follows immediately. 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?

There is no output schema, so the description carries the burden of describing what comes back, and it only loosely characterizes the result ('how cited competitor pages differ'). For a single-parameter read tool it is adequate but thin — the shape of the comparison output and use of the required id remain 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?

Schema description coverage is 0% and the description never mentions project_id or its expected form. With one parameter and a non-obvious scope ('already read' content implies per-project state), the description should clarify what the project argument selects, but it does not compensate for the coverage 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 states a specific comparison resource: how cited competitor pages differ from the user's on topics they win. This distinguishes it from siblings like read_perception or read_performance, though the leading phrasing is output-oriented rather than a crisp verb+resource. An agent can tell what it returns, but the 'read' action is implied rather than stated.

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

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

It gives explicit timing guidance: 'Use it before rewriting a page to compete.' That is a clear when-to-use trigger. It stops short of naming alternatives or when-not-to-use conditions, so it is not 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds a non-obvious data-interpretation caveat ('Missing coverage is not zero') that prevents the agent from misreading absent data as zero, which is real value beyond structured fields. It still says nothing about pagination despite a cursor parameter existing.

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 resource and immediately listing the selectable views, then closing with the key caveat. No filler, though the view list is dense enough that it could be tied more explicitly to the enum values.

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 0% schema coverage, the description leaves most parameters and the pagination model undocumented. It covers the view dimension and one interpretation caveat but is far short of what an agent 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 description coverage is 0% across 12 parameters, so the description must carry the load and largely does not. It gestures at the view enum values ('summary, per crawler, log coverage, individual requests') but never explains limit, range, cursor, bot_id, folder, status, start_date, end_date, verification, or resource_class.

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 (reads AI crawler requests from server logs) and enumerates the four view modes, so the agent knows exactly what the tool returns. It does not, however, name or distinguish itself from the nearby sibling read_ai_crawlability, leaving that routing to inference.

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

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

The mapping of views to use cases (summary vs per crawler vs coverage vs individual requests) implies how to pick granularity, which is genuine usage signal. But there is no explicit when-to-use / when-not guidance and no reference to alternative tools such as read_ai_crawlability or read_ai_referrals.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the data is the 'latest' snapshot and volumes are 'provider estimates,' which tells the agent how much to trust the numbers. It does not, however, describe return format or pagination.

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 the core content (what is searched, volumes, change) front-loaded and no wasted words. The provenance caveat is correctly appended rather than leading.

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, annotation-covered read tool with no output schema, the description is adequate about content but incomplete on routing: in a crowded read_* namespace it does not tell the agent when to pick this over read_search_intelligence or read_search_dataset.

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

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

With schema coverage at 0%, the description must compensate for the sole parameter, project_id, but it never mentions it or explains the required project scoping. The agent gets no semantic help beyond the raw uuid type in the schema.

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

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

The description states a clear verb+resource combination: it returns search demand for a market, including volumes and change over time. It is concrete about content, but among a large set of sibling read_* tools (read_search_intelligence, read_search_dataset, read_query_evidence), it never distinguishes itself from those alternatives.

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

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

There is no explicit when-to-use, when-not-to-use, or named alternative. Usage is only loosely implied by the phrase 'in this market,' leaving the agent to guess how this differs from the other read_* demand/query 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 cover read-only/idempotent/no-destructive, so the bar is lower, and the description adds genuinely useful semantics the annotations cannot: which accuracy_state values mean 'no value, never zero', that inconclusive/not_covered are not answer errors, and that cited sources accompany a contradiction rather than cause it. It stops short of describing pagination or response shape.

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

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

Front-loaded with the resource definition, which is good, but the back half is a dense cluster of caveats packed into long sentences with no visual separation, making the interpretation rules harder to scan than they need to be.

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

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

For a 10-parameter, no-output-schema tool this covers the important semantic pitfalls around accuracy_state and source attribution, but leaving nearly all input parameters unexplained is a material gap given the low schema coverage.

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

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

With 10 parameters and only 10% schema description coverage, the description must carry parameter meaning, but it explains almost none of view, limit, topic, cohort, engine, verdict, cursor, audit_id, or market_id. The accuracy_state values it discusses are output states, not input parameters, and only 'latest or a chosen run' loosely hints at run selection.

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: factual claims made by AI answers in a run, checked against the brand's confirmed facts, with accuracy and coverage. This is a distinct dataset from siblings like read_perception or read_visibility_results, so an agent can differentiate it, though the description never names an alternative explicitly.

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 real interpretive guidance ('Always state the coverage and quote the fact', 'inconclusive and not_covered are not errors') and implies choosing the latest vs a specific run, but never says when to prefer this tool over read_perception, read_query_evidence, or read_visibility_results.

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 the safety profile is covered. The description adds that the response concerns connection state and import progress, but with no output schema it never says what the returned status values look like or whether errors are reported per source.

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 the payload described first and the usage trigger second; no filler. The closing phrase 'before reading it again' is slightly ambiguous about which read is being retried.

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 one trivial parameter, no output schema and safety already covered by annotations, the description is close to sufficient for a diagnostic read. It still leaves the return shape (a per-source status list? a boolean?) and the behavior when nothing is connected unspecified.

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

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

Schema description coverage is 0% and the description never mentions project_id, so it adds no meaning beyond the schema's bare uuid-typed property. The description does not clarify whether the status is scoped to a single project or aggregated across connections.

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 specifically what the tool returns: which data sources are connected (Search Console, GA4, server logs) and how far their import has progressed. The verb 'read' and the resource (integration status) are identifiable, though it does not explicitly distinguish itself from the many other read_* siblings by name.

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

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

Gives an explicit trigger: use it when a traffic or search read is unavailable, and before retrying that read. That routes the agent away from blindly re-calling the failing read tool, though it never names which sibling failed or what to do if integrations come back healthy.

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), and the description adds genuine extra context: perception_state of pending/unavailable/no_mentions means there is no value rather than zero, coverage must always be stated, and the semantic caution that cited sources are not the cause of criticism. That is real interpretive behavior beyond 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?

The metric definition is front-loaded and the coverage caveat is well placed, but the two long, clause-heavy sentences (and the awkward 'sources cited alongside criticism, never its cause') reduce scannability for a read tool with a large parameter surface.

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, yet the description only sketches the shape of the response and says nothing about pagination via cursor/limit, what cohorts or views select, or how to pin a specific run. For an 11-parameter read tool this leaves the agent guessing at 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 9% across 11 parameters, so the description must compensate and largely does not. Only 'latest or a chosen run' hints at the audit_id/run selector; enum-bearing parameters (cohort core/comparison, view summary/quotes, theme, engine, polarity, entity, market_id) are left completely unexplained.

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

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

States a concrete verb+resource with the substance of what is returned (net sentiment -100 to +100, coverage, themes, quotes, sources) and scopes it to the latest or a chosen run. It reads as a distinct 'perception' reader, though it never names which sibling (e.g. read_visibility_results, read_query_evidence) it should be preferred over.

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?

'Latest or a chosen run' loosely implies when to call it, and the coverage caveat tells the agent how to interpret the result. There is no explicit when-to-use/when-not-to-use guidance relative to the many read_* siblings, so usage remains implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real behavioral context the annotations cannot: 'not_connected means no search data source is connected, which is not zero' — a meaningful distinction for interpreting results. It omits pagination/cursor behavior, so it is not fully complete.

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 dense sentences with no filler, and the core purpose leads before the parameter detail. The packed, run-on clauses for range values slightly hinder scanning but nothing 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?

For a 12-parameter tool with no output schema, the description explains range and dimension but is silent on pagination (cursor), result sizing (limit/sort), and the compare options and their paired date fields. The not_connected note is a highlight, but an agent still lacks enough to use several parameters correctly.

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

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

Schema description coverage is 0% across 12 parameters, so the description carries the burden. It clarifies the range default, the custom cross-field prerequisite, and the dimension breakdown values, but leaves sort, limit, cursor, compare, granularity, and the compare_* date fields unexplained. It adds value beyond the schema without compensating for the full coverage 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?

States a specific verb+resource: it returns Search Console and GA4 totals for a range, with optional comparison. That is concrete and far better than a restatement of the title. It does not, however, distinguish itself from near-neighbors like read_search_dataset or read_visibility_overview, so an agent still has to infer which read tool applies.

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

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

Usage is implied through parameter guidance: it explains valid range values, the default (last_synced), that custom requires start_date and end_date, and that dimension produces a breakdown. There is no explicit when-to-use or when-not-to-use statement, and no alternative tool is named for overlapping 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?

Annotations already establish the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context beyond that: core prompts carry scores while comparison prompts are reported separately, which affects how results should be interpreted. It omits pagination behavior and result size, keeping this at a 3.

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 with the resource statement front-loaded and no filler. Nothing is redundant, though the phrasing is a noun fragment rather than a self-contained statement of what the tool does.

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?

This is a paginated read tool with 6 parameters, 17% schema description coverage, and no output schema. The description omits the existence of paging (cursor/limit), the default-false active_only filter, and how the two cohorts are returned in a response, so an agent lacks the context to call it efficiently or 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 description coverage is only 17% (just the cursor param), so the description must carry the load for 6 parameters. It adds real meaning for the cohort enum by explaining core vs comparison, but says nothing about active_only, limit boundaries, prompt_set_id, or the required project_id, leaving most parameters semantically thin.

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

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

The description names the resource (tracked prompts) and enumerates the payload fields (topic, intent, status), so an agent knows what comes back. It also distinguishes the two cohorts, but it never explicitly states the verb or contrasts itself with siblings like read_visibility_results or read_performance, which also surface prompt-adjacent 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?

There is no guidance on when to call this versus sibling read tools, nor any prerequisite (e.g. needing a project_id or a prior paginated call). The only implicit usage signal is the core/comparison split, which hints at the cohort parameter but does not say when either branch 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the meaningful behavioral constraint that dates must be an exact saved window and are inclusive, but says nothing about pagination behavior despite the cursor parameter.

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

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

A single front-loaded sentence with no filler; the key scoping constraint (exact saved window, inclusive) comes first. It is efficient, though arguably too terse given the parameter surface.

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 read tool with 13% schema coverage and no output schema, the description is thin. It omits pagination semantics, filtering behavior, and what the returned evidence looks like, leaving the agent under-informed on key details.

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 only 13% (just cursor), so the description carries most of the burden and largely fails. It clarifies inclusive date semantics for window_start/window_end but leaves query, limit, site_url_id, and resolution_outcome unexplained.

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

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

The description names the resource precisely (Search Console queries matched to site pages) and the scope (an exact saved window with inclusive dates), which is more specific than the tool name alone. It does not distinguish itself from siblings such as read_search_dataset or read_performance, but the resource is clear enough to identify the operation.

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

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

There is no statement of when to use this tool versus alternatives, nor any prerequisite about needing a previously saved window. The agent must infer that this is a read of pre-saved evidence rather than an ad-hoc query.

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 this as a safe, read-only, idempotent, closed-world operation, so the bar is lower. The description adds useful data-granularity context by clarifying that referring-domain and page totals are aggregates rather than individual links, but it does not discuss pagination, authentication, or other behavioral traits.

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

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

The description is two short, front-loaded sentences with very little waste. The first identifies the returned resource, and the second immediately adds the aggregate caveat, so it is concise and well-structured despite being slightly fragmentary.

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 six parameters, only 17% schema description coverage, and no output schema, the definition should explain parameter behavior and return shape more fully. It gives only a high-level content note and omits pagination, sorting, limiting, and required identifier semantics.

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 only 17%, and the description provides no meaning for project_id, dataset_id, sort, limit, direction, or cursor. It fails to compensate for the low schema coverage, leaving parameter usage almost entirely undocumented.

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 that the tool returns rows of a keyword or backlink dataset, which identifies the specific resource and output shape. It is clear, but it does not explicitly distinguish this tool from related read_search_* or read_query_evidence siblings, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives, prerequisites, or which dataset types are appropriate in which situations. The description only states what is returned, leaving usage entirely implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds the useful chaining context that returned ids are consumed by read_search_dataset, but says nothing about pagination, empty-project behavior, or dataset staleness.

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, zero filler. The return value is front-loaded and the routing instruction follows immediately after.

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 dataset list plus ids. For a single-param read-only tool whose annotations carry the safety profile, that is close to sufficient; only pagination and edge-case behavior 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 (project_id) and schema description coverage is 0%. The description implies project scoping ('for this project'), which matches the parameter name, but adds no format, default, or sourcing detail beyond the self-evident name.

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

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

The description names the exact resource set it returns (keyword, competitor, backlink datasets with their ids) scoped to a project, and explicitly distinguishes itself from the sibling read_search_dataset. It lacks an explicit leading verb like 'list', but the intent is unmistakable.

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

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

It routes the agent to the correct follow-up tool: 'Pass a dataset_id to read_search_dataset for its rows.' That is clear when-to-use-this vs. when-to-use-the-sibling guidance, though it doesn't say when this tool is unnecessary (e.g., if you already hold a dataset_id).

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 the safety profile is fully covered without the description. The description adds the default-resolution behavior (latest crawl when no snapshot is given), which is genuine context beyond the annotations, but says nothing about response shape or limits.

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

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

A single compressed sentence with the resource and payload front-loaded and no filler. It is slightly telegraphic as a noun phrase rather than a full clause, but nothing 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?

For a two-parameter, read-only tool with no output schema, the description covers the core scope and default behavior adequately. It leaves gaps around the sibling render_site_health relationship and what the returned 'top issues' actually contain.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies that snapshot_id selects a specific snapshot versus defaulting to the latest crawl, but says nothing about project_id (the required parameter) or the UUID format expectations.

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 (Site Health) and names the concrete payload: scores, coverage, and top issues. It does not differentiate itself from the sibling render_site_health, so an agent must guess at the read-vs-render split.

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 phrase 'for the latest crawl, or a chosen snapshot_id' implies the two usage modes (default to newest, or target a specific snapshot), which is useful conditional guidance. However, it never states when to prefer this over render_site_health or the other read_* visibility tools, so alternatives are 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, non-destructive and closed-world, so the safety profile is covered. The description adds useful detail about the returned diagnostics, but says nothing about pagination (limit/cursor) or defaulting to the latest crawl when crawl_id is omitted.

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, and the primary purpose is front-loaded ahead of the usage hint. Nothing extraneous is present.

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 summarizes the return shape (link counts per page plus sampled/linked pages and anchor diagnostics), which is the key missing structured data. It is only slightly short on pagination and crawl-default behavior for a 5-parameter tool.

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

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

Schema description coverage is only 40%. The description names site_url_ids and its provenance (from read_site_pages), partially compensating, but leaves limit, cursor, project_id and the 'omit for latest crawl' behavior of crawl_id to the schema 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 and resource: internal link counts per page for a crawl. It also signals the diagnostic content (sampled linking/linked pages, anchor diagnostics) and names read_site_pages as the source of IDs, giving an agent a concrete handle on what this returns.

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 implies a workflow ('pass site_url_ids (from read_site_pages)') for batching several pages, but gives no when-to-use vs alternatives such as read_site_health or read_site_pages, and no exclusions or prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds the meaningful behavioral context that results are paged and that issue rule_ids are grouped by finding class, plus where the rule_id input comes from. It does not explain pagination termination or result sizing, keeping it below 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-loads what is returned, then covers the two main filtering modes and the sibling relationship in two dense sentences. Every sentence carries information, though the phrasing is compressed to the point of being slightly terse.

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 enumerates the shape of each returned page and explains the paging model, which is the key gap. A 7-parameter tool at 43% schema coverage could still say more about pagination limits and cursor lifecycle.

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 43%; the description explains the intent of rule_id (duplicating the schema) and gives loose semantics for page_kind/status filters, but adds nothing for limit, and only implicitly touches cursor/crawl_id. It partially compensates for the coverage gap rather than closing it.

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 ('Pages from a crawl') and enumerates the returned fields (URL, title, page type, status, scores, issue count, rule ids by finding class). It also explicitly differentiates itself from sibling read_site_health as the totals view.

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 conditions: pass rule_id (sourced from read_site_health top_issues or an issue group) to list pages affected by an issue, and filter by page_kind/status to find pages by type or status. It names the relationship to read_site_health but stops short of explicit when-not-to-use 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/destructiveHint and closed-world scope, so the safety profile is covered. The description adds real value beyond that by disclosing the return contents (citing prompts and engines, brands listed, own-brand presence), which matters since there is no output schema. It stops short of permission or pagination/scope caveats.

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, front-loading the resource and return contents. The clipped, fragment style is efficient, though it borders on cryptic rather than fully structured, keeping it below 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?

For a 6-parameter tool with 0% schema coverage and no output schema, this definition is under-specified: it omits the semantics of most parameters and any scoping or filtering behavior. The one useful addition (return contents) does not make up for the missing parameter and usage 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 description coverage is 0% across 6 parameters, so the description is expected to compensate and largely does not. It only touches audit_id ("Omit audit_id for every run") and never explains cohort, engine, market_id, or project_id, leaving the two enums and two UUID filters undocumented anywhere.

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 fragment "One cited URL: the prompts and engines that cite it, the brands it lists and whether your brand is on it" clearly scopes the tool to a single cited URL and enumerates what it surfaces (citing prompts/engines, listed brands, own-brand presence). An agent can tell this apart from bulk listing tools, though it does not explicitly name the closest sibling such as read_visibility_sources. The telegraphic, verb-less phrasing keeps it from a 5.

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

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

The only guidance is "Omit audit_id for every run," which is a single-parameter directive rather than a when-to-use statement. Nothing explains when this single-URL read is preferred over the many other read_* siblings (e.g., read_visibility_sources, read_query_evidence). No exclusions or alternatives are offered.

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 a closed world, so safety is covered. The description adds the meaningful 'each market is measured separately – never pool markets' caveat beyond annotations, but discloses nothing about return structure, pagination, or how runs are selected.

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 compact sentences front-load the returned content before the parameter guidance, with no filler. Sizing is appropriate for the tool's complexity.

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 0% parameter coverage, the description should carry more of the burden. It sketches the returned metrics and key param conditions, but omits explanation of cohort, engine, audit_id and the overall response shape, leaving gaps for a 6-parameter read tool.

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

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

Schema description coverage is 0%, so this 6-parameter tool relies entirely on the description for parameter meaning. It only explains baseline_id and market_id, leaving cohort, engine, audit_id, and project_id undocumented anywhere, which is inadequate compensation.

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

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

The description names the specific metrics returned (mention rate, citation rate, competitor rankings, run status) and the run scope (latest or chosen), which is clear content. However, it does not distinguish this 'overview' from close siblings like read_visibility_results, read_visibility_trends, or read_visibility_sources.

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 conditional guidance for two parameters (pass baseline_id to compare runs; pass market_id for non-default markets, never pool markets), which is useful calling guidance. But it never states when to choose this tool over the other read_visibility_* siblings, leaving the primary selection decision to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds that results are 'paged' (implying cursor-based navigation) and discloses return contents (answers, mentions, cited sources), but says nothing about auth needs, rate limits, or what empty results mean.

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

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

Two sentences, front-loaded with what the tool returns before the usage clause. No filler; every clause carries information about either output or filtering.

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 only 22% param coverage across 9 params, the description should carry more weight. It sketches the return shape (answers, mentions, sources) and the main filters, but omits pagination mechanics, engine/cohort selection, and result semantics for an agent to invoke confidently.

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 only 22% and there are 9 params, so the description must compensate more than it does. It usefully explains the intent behind the filter params (prompt_id, domain, url) as a means 'to read fewer', but leaves engine, cohort, limit and cursor undescribed beyond what the schema's enums/defaults already imply.

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

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

The description names a specific resource - 'the answers engines gave in one run, with mentions and cited sources' - which an agent can distinguish from sibling read tools like read_visibility_overview (audit-level) or read_visibility_trends (time series). It is clear and concrete, though it doesn't explicitly contrast itself with read_visibility_sources, which also concerns sources.

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

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

'Use it to see what an engine said for a prompt' gives a clear use context, and 'filter by prompt_id, cited domain or URL to read fewer' tells the agent how to narrow results. It lacks explicit when-not-to-use guidance or named alternatives among the many read_visibility_* siblings.

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, so the safety profile need not be restated. The description usefully adds that results reflect the latest or a chosen run and include competitor listings and citation frequency, but says nothing about pagination behavior, ordering, or result size beyond what the schema hints at.

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 what the tool returns, then the level/domain semantics, then the use case. Dense but no wasted sentences; the first sentence is a little packed.

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 9 params at 22% coverage, the description covers the conceptual core well but leaves several filter params unexplained. Adequate for selecting the tool, thin for configuring 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 only 22% across 9 params, so the description must compensate and it does so partially: it explains level (domain=publishers, url=pages) and the domain parameter's role, and alludes to audit_id via "latest or a chosen run." It leaves cohort, engine, market_id, limit, and cursor undocumented.

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 resource — the domains/URLs that engines cited — plus the added dimensions (frequency, whether you or competitors are listed). This differentiates it from siblings like read_visibility_overview/trends/results without naming them explicitly.

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

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

"Use it to find the sources to earn a place on" gives a motivation and implied context, but there is no explicit when-not or pointer to an alternative among the many read_visibility_*/read_source_url siblings. Usage is implied rather than prescribed.

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, so the bar is lower. The description then adds genuinely useful interpretive behavior: series with different comparison keys are not comparable, and gaps mean missing runs rather than zeros. That prevents an agent from misreading the data, though nothing is said about auth scope or result size.

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 the purpose front-loaded and no filler. The second sentence is dense but every clause carries operational value; only the omission of sibling routing keeps it from being exemplary.

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 9 parameters at 0% schema coverage, no output schema, and no sibling differentiation, the description is underspecified for a tool of this complexity. It omits the meaning of the cohort enum and the granularity/engine dimensions that define what the returned points actually are.

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

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

Schema description coverage is 0% across 9 parameters, so the description must carry the load and largely does not. "Explicit window" loosely maps to from_at/to_at and "comparison keys" gestures at cohort/engine/market_id, but granularity, transport_model, retrieval_enabled, and the core-vs-comparison cohort meaning are entirely unaddressed.

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 resource and dimension: visibility measured over time (a trend/time-series read). This is clearly distinct from a snapshot-style read, but it never names or contrasts the adjacent siblings read_visibility_overview, read_visibility_results, or read_visibility_sources, so an agent must infer when this one applies.

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?

"For an explicit window" implies that from_at/to_at must be supplied deliberately rather than defaulted, which is a usable hint. However there is no when-to-use/when-not guidance and no routing to alternative visibility tools, so usage is only implied.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds 'Runs at once,' which usefully signals immediate execution rather than a staged workflow, but it omits any detail about side effects, permissions, or references affected by the rename.

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 very short sentences, front-loaded with the core action and followed by the key behavioral note. There is no filler or redundancy.

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

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

For a simple rename operation whose safety profile is already covered by annotations and which has no output schema, the description is minimally adequate. However, it leaves parameter meanings, prerequisites, and any effect on related resources unexplained, which matters for a mutation tool.

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

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

Schema description coverage is 0% across three required parameters (project_id, topic_id, name). The description provides no meaning, format, or constraint information for any parameter, so it fails to compensate for the completely undocumented schema.

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

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

The description states a specific verb and resource ('Rename one topic'), making the operation unambiguous. It does not explicitly distinguish itself from the sibling create_topic or the prepare/confirm rename flow, but the core purpose is clear.

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

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

No when-to-use guidance, prerequisites, or alternatives are given. 'Runs at once' hints at immediate execution but does not tell the agent when to choose this over siblings like create_topic or the prepare/confirm pattern.

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 safety, so the behavioral bar is lower. The description adds that the output is 'interactive' (a rendered view rather than raw data) and that a snapshot is optional, defaulting to 'latest', which is genuinely useful context. It does not add caveats, limits, or return-format detail beyond that.

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

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

A single clean sentence with the core scope front-loaded and no wasted words. It is efficient, though arguably terse given the ambiguity around what 'interactive' produces.

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 0% schema coverage, no output schema, and a confusingly similar sibling, the description leaves too many gaps: project_id is undocumented, the render-vs-read distinction is unaddressed, and the nature of the returned view is unclear. It is not sufficient for an agent to call this confidently.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clarifies snapshot_id semantics ('latest or a chosen snapshot'), but the required project_id parameter is entirely unexplained. Partially compensating for the coverage gap is not enough for two undocumented params.

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 verb and resource ('Show an interactive Site Health view'), and scopes it to 'the latest or a chosen snapshot', so the basic function is understandable. However, it does not differentiate from the close sibling 'read_site_health', leaving an agent unable to tell whether this renders a view versus returns data. 'Interactive view' remains vague.

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

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

There is no explicit when-to-use guidance and no alternatives named. Given a nearly identical sibling ('read_site_health'), the definition should say when to pick render_site_health over it, but gives no such routing. Only the implicit 'latest or a chosen snapshot' hints at usage.

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=true, idempotent=true, destructive=false and closed-world, so the safety profile is covered. The description adds only 'interactive' and the notion of a time window; it says nothing about pagination (cursor), result limits, or how filters combine, leaving the behavior of a 15-parameter read largely undisclosed.

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

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

A single well-formed sentence with the view modes front-loaded and zero filler. It is efficient, though its brevity reflects under-specification rather than tight editing.

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 tool with 15 parameters, one required, no output schema, no parameter descriptions and no annotations gap to lean on, the description is far too thin. An agent cannot tell which optional filters to supply, how to paginate, or how this renderer differs from the read_visibility_* siblings.

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

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

Schema description coverage is 0% with 15 parameters, so the description must compensate and largely does not. It gestures at three (view modes), the window (from_at/to_at) and one run (audit_id/snapshot_id), but level, limit, cohort, cursor, domain, engine, competitor, project_id, transport_model and retrieval_enabled receive no explanation at all.

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 concrete verb+resource ('Show an interactive visibility view') and enumerates its three modes (overview, trends, sources), which maps directly to the view enum. However, it does not distinguish this tool from siblings read_visibility_overview, read_visibility_trends and read_visibility_sources, which appear to cover the same ground; the render-vs-read distinction is left implicit in the word 'interactive'.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no comparison against the four read_visibility_* siblings that overlap with each view mode. The phrase 'for one run' weakly hints at scoping via audit_id/snapshot_id but is never tied to a parameter or condition.

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 safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower. The description adds genuine value beyond them: it discloses the return shape (matching records with ids) and the intended handoff to fetch, though it omits pagination/limit 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 tight sentences, zero waste, with the primary purpose and scope front-loaded and the follow-up action trailing. Nothing needs trimming.

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

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

For a simple search tool with no output schema and annotations covering safety, the description is nearly complete: purpose, scope, return shape, and next step are all present. The main gap is undocumented parameter semantics for limit and project_id.

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

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

Schema description coverage is 0% for three parameters, so the description carries the full burden. "By text" loosely implies the query parameter, but limit and project_id (project scoping) are entirely undocumented in both schema and description, leaving important semantics unstated.

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) and enumerates the exact resources it searches (projects, active Actions, prompts), scoped by text. It also names the follow-up sibling (fetch) for full records, letting an agent place it precisely among the many read_* tools.

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

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

Gives a clear when-to-use condition ("when you do not know where a record is") and points to the follow-up tool (fetch) for the complete record. It stops short of explicit when-not guidance or contrast with the read_* siblings, so it is clear context without full 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 the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the description only needs to add context. 'Runs at once' usefully signals synchronous, non-scheduled execution and implicitly confirms the change is applied immediately. It omits what a reopen restores, permission requirements, and any post-change effects.

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, front-loaded sentences with no filler; the operation is stated first and the execution trait second. 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 a three-required-parameter mutation with no output schema and no nested objects, the description is close to minimally viable. It lacks any pointer to how an agent obtains a valid action_id or what the resulting state looks like, though annotations cover reversibility safety.

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

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

Schema description coverage is 0% across three parameters, so the description must compensate. It maps the two enum values to intent ('dismiss'/'reopen' -> dismissed/open), which is genuinely additive, but project_id and action_id semantics and any linkage between them remain unexplained.

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 ('Reopen or dismiss one Action') and enumerates the only two state transitions, which is more informative than the title alone. It does not name the sibling read_actions as the companion lookup tool, so differentiation is left implicit.

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

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

No when-to-use guidance, no prerequisites (e.g. that you need an action_id obtained from read_actions), and no exclusions relative to siblings. The only hint is 'Runs at once', which is a timing trait rather than selection 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 the safety profile (readOnly=false, idempotent=true, destructive=false), so the bar is lower. The description still adds genuine behavioral value beyond them: 'Runs at once' (immediate effect, no staging) and 'earlier measurements keep the old wording' (historical data is not retroactively rewritten).

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 waste, and the action is front-loaded ahead of the side-effect note. 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 mutation tool with no output schema, the description covers the key consequence (old measurements untouched) but omits permissions/auth requirements, whether the updated prompt is returned, and any explanation of the required parameters. Adequate but with clear gaps given 0% schema coverage.

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

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

Schema description coverage is 0% and all three required parameters are undocumented in both schema and description. The phrase 'the wording of one tracked prompt' weakly implies text is the new wording and prompt_id identifies the target, but the 300-character cap and the project_id parameter are never addressed.

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: 'Replace the wording of one tracked prompt.' It is clearly distinguishable from sibling mutations like rename_topic or update_action_status, though it never explicitly contrasts itself with the prepare_*/confirm_change workflow 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?

'Runs at once' implicitly signals that this is the immediate-execution path as opposed to the prepare_ then confirm_change sibling pattern, which is useful context. However, it never names that alternative or states when NOT to use this tool, leaving the routing to inference.

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