Hyperresearch

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only the existence of an optional audit detail, and says nothing about consequences of abandoning (e.g., whether the escalation is closed permanently, whether related runs are affected) or what re-invocation with the same id does.

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 no filler, front-loaded with the action. It is efficient, though arguably under-specified rather than overly concise.

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 mutation whose annotations already convey destructiveness and idempotency, the description is minimally adequate. It is missing the outcome of abandoning and its relationship to resolve_escalation/claim_escalation, which an agent needs to route correctly.

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

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

Schema description coverage is 100%, and the schema already documents both escalation_id (from list_escalations) and detail (audit-trail reason). The description's phrase 'optional audit detail' merely restates the schema, so baseline 3 applies.

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

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

The description names a specific verb and resource ('Abandon an escalation'), which is clear enough to act on. However, it does not distinguish itself from the closely related siblings claim_escalation and resolve_escalation, so the agent must infer the difference between abandoning and resolving.

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 abandon rather than resolve or claim an escalation, nor any mention of prerequisites such as ownership or state. The agent is left to infer the correct branch of the escalation workflow purely from the verb.

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, destructiveHint=false. The description adds rich context: nothing has been charged until this call, the reservation/allowance/launch all happen here, and timeout behavior is described. This goes well beyond 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?

Front-loaded with the core action and state. Information is dense but well-organized, though slightly lengthy for a tool description. Every sentence adds value, but could be marginally tightened.

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

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

Complete for the tool's complexity. Given no output schema, it explains return behavior implicitly (run starts), covers timeout, charging, and default behavior. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100% so baseline is 3. The description adds valuable semantics: 'Answer by axis, not by position', send 'you_decide' or empty string for undecided, and skip:true accepts all assumptions. These details are not in the schema descriptions and clarify how to use the parameters effectively.

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: 'Answer the clarification questions a run with status "clarifying" is waiting on, and start it.' This is precise and distinguishes it from siblings like start_run or run_status by explaining exactly which state it operates on.

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

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

Explicitly says when to use it (only when a run is 'clarifying') and even tells agents that 'most agents never need this tool' because runs default to clarify:"auto". It also explains the alternative (skip vs answer by axis) and what happens on timeout.

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, openWorld and non-destructive, yet the description adds substantive behavior: the conditional `licensing` payload fields, the no-vendor-request guarantee, and the untrusted-source delimiter wrapping with prompt-injection guidance. This is well beyond what structured fields provide.

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

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

Three tight sentences, front-loaded with the primary return contract, then conditional licensing behavior, then the safety note. No wasted clauses, though the licensing field list makes the middle sentence dense.

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 properly carries the return contract (note, not-found, conditional licensing object, delimiter wrapping). It covers the main cases well; only edge behavior like error/failure responses or note staleness 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?

Only one parameter and schema coverage is 100%, so the schema already documents the url field fully. The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: return the vault note for a URL if already fetched, else a not-found result. An agent can distinguish it from fetch_url by the 'has been fetched' condition, though the description never names that sibling 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?

Usage is implied rather than stated: it is a lookup that makes no vendor request when licensing is off or the publisher is unlicensed, which hints at 'check before fetching'. There is no explicit when-to-use/when-not or named alternative among the many 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 declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description only needs to add claim-specific behavior. It contributes the domain context (queued, browser-lane, customer-owned agent) but never says whether claiming takes an exclusive lock, whether the claim expires, or what happens if another agent holds it — the core behavioral question for a claim operation.

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

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

One sentence with no filler, and the operative verb and scope are front-loaded. It is efficient, though arguably under-sized for a state-changing operation rather than padded.

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

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

For a one-parameter mutation with no output schema, the description covers the what and where but not the consequences of claiming or what the call returns (e.g. whether a handle/session is handed back). Adequate but leaves the agent guessing about the post-claim state.

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

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

Schema description coverage is 100% and the single parameter's schema text already says "An escalation id from list_escalations," which is the only useful semantic an agent needs. The description adds nothing beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ("Claim ... escalation") and narrows it with scope qualifiers: queued, browser-lane, customer-owned agent. An agent can distinguish it from list_escalations and abandon_escalation, though the description never names those siblings or explicitly contrasts the operations.

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 precondition "queued" — you claim an escalation that is waiting before working it. There is no explicit when-to-use vs alternatives guidance and no statement of when not to claim (e.g. already-claimed or non-browser-lane escalations), leaving the agent to infer the 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered without the description doing any work. The description adds only that the run is 'hosted' and that resume can carry a revised budget, but says nothing about irreversible state transitions, whether abort on an already-aborted run is a no-op, or what a caller receives back.

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

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

Two sentences, zero filler, front-loaded with the action set and the resource. Nothing in the text is redundant with the title or padded.

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

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

With no output schema the description should ideally say what comes back (e.g., updated run state), and it should note the precondition that the target run exists and is in a controllable state. Still, it covers all three actions plus the one conditional parameter, which is sufficient for a simple three-action control tool whose annotations and schema are rich.

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

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

Schema description coverage is 100% and the action enum, budget deprecation notes, and run_id provenance are all documented in the schema itself. The description's one parameter-adjacent line ('Resume may supply a revised budget') restates the budget schema description rather than adding format, constraint, or interaction detail. Baseline 3 applies when the schema carries the load.

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 three concrete verbs (pause, resume, abort) against a specific resource ('hosted research run'), so an agent immediately knows this is the lifecycle-control tool rather than a read tool like run_status or a creation tool like start_run. It stops short of naming any sibling explicitly or stating which run states each action applies to.

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: nothing says the run must be in-progress to pause, that abort is terminal (that fact lives only in the schema enum), or when rerun_from is preferable to resume. The only conditional statement ('Resume may supply a revised budget') is parameter guidance, not usage 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description adds the `type note only` constraint but does not say what happens on duplicate titles, whether tags auto-create, or what is returned. With annotations covering the safety profile, a 3 is appropriate.

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

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

A single, front-loaded sentence with no waste, though it omits any further useful context. Efficient but minimal.

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 five-parameter mutation tool with no output schema, the description is thin: it does not explain behavior on duplicates, tag handling, or the return value. Annotations cover the safety profile, so it is not inadequate, but gaps remain.

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

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

Schema description coverage is 100%, so the schema documents all five parameters including formats and limits. The description adds no parameter details beyond the type restriction, so baseline 3 is correct.

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 (Create) and resource (a note) plus the constraint that only type `note` is supported, and scopes it to `your workspace vault`. This distinguishes it from the sibling update_note and read_note.

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 guidance on when to use this vs. alternatives like update_note or list_notes, and no mention of required prerequisites (e.g. title/body). The type restriction is the only scope hint.

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

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

Goes well beyond the idempotentHint annotation by spelling out the exact idempotency semantics: exact match after trimming is case-sensitive and includes archived projects, returns created:false, never duplicates, and a retry with the same idempotency_key replays the first answer. It also discloses cost ('Free') and the archived-project constraint.

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

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

Dense but front-loaded: purpose, idempotency, archived behavior, cost, and the next-step call are packed into a short block with no filler. The trailing example earns its place for the required name param.

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

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

An output schema exists, so return values need not be explained, yet the description still flags the key return signal (created:false). For a create tool with a shared-scope side effect, the description covers permissions-adjacent behavior, idempotency, and the downstream call completely.

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

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

Schema description coverage is 100%, so all three parameters (name, description, idempotency_key) are already documented in the schema, including the trimmed/case-sensitive match rule and the 24-hour idempotency replay. The description's example {"name":"Acme market entry"} adds minor value but does not meaningfully exceed the schema.

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

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

States a specific verb+resource ('Open a project') and clarifies the scope model ('they share one vault scope, and each builds on sources earlier ones kept'). It is clearly distinguishable from siblings list_projects and start_run, which it references 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?

Explicit when-to-use guidance: call list_projects first and reuse a fitting project; then pass project.id as project_id to start_run. It also states the when-not case (archived project takes no runs – ask the person to reopen it or pick another name).

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 (not read-only, not destructive, not idempotent). The description adds that the export is queued asynchronously and produces a portable tar.gz, which is useful context, but it omits return behavior, job tracking, or rate 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 front-loaded sentence with no wasted words. The key action and output format are stated immediately.

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 no-parameter, low-complexity tool, the description covers the core action but leaves gaps around what is returned (e.g., a job identifier) and how to monitor progress, which is especially relevant without an output schema.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to add parameter semantics, and none are present.

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 ('Queue'), resource ('portable tar.gz export'), and scope ('authenticated workspace vault'). It is clear but does not explicitly differentiate itself from siblings such as vault_job_status or vault_status.

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 guidance on when to use this tool versus alternatives, nor any conditions or prerequisites. The action implies its own use case, but no usage context is provided.

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 mutation, non-idempotency, and open-world behavior, so the description adds real value on top: the async job model, the required polling step, the cost ladder ($0.02 for Firecrawl), and workspace restrictions. It does not discuss auth or retry/idempotency behavior, but the behavioral picture is otherwise strong.

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 dense sentences, front-loaded with the action, then the async workflow, then cost, then constraints. No filler and every sentence carries information an agent needs.

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

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

With no output schema, the description compensates by explaining the return shape (job_id, poll_url) and the terminal result fields (result.note_id or result.escalation_id). Combined with the annotations, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so the schema already documents url, tags, provider, and rung_max including the enum meanings. The description's cost note largely duplicates the provider schema description, adding only the ladder framing, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Queue one URL ... into the vault') and frames the operation as an async enqueue, which is distinguishable from siblings like create_note or read_note. An agent can tell what this does without opening the schema.

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

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

Explicitly tells the agent to poll vault_job_status until done, and explains the cost implications of allowing firecrawl providers. It does not state when to prefer alternative sibling tools or when not to call it, so it falls short of full when/when-not guidance.

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

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

Beyond the annotations (which only flag non-read-only, idempotent, non-destructive), the description discloses the actual side effect: notes are retagged project:<id>, join that project's search scope, and are reused by later runs there. It also reassures that nothing is rerun or charged and names the refusal error, which the annotations cannot convey.

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

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

It is front-loaded with the core action and then layers constraints efficiently. The closing sentence about filing into the current project versus a different one partially repeats the schema's move description, but the redundancy is small and the whole passage stays dense and purposeful.

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 annotations and an output schema, the description supplies the missing behavioral context: preconditions, refusal mode, side effects on notes and search scope, and the move gate. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by tying move to the cross-project scenario and framing it as the thing that changes whether the call succeeds. It also supplies a concrete example payload with both required ids.

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

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

The description gives a specific verb and resource ('File a run you already started under a project') and anchors it to a familiar console action. It is immediately distinguishable from siblings like start_run, rerun_from, and list_runs, which do different things to runs.

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

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

It states exactly which run states are filable (queued, done, failed, aborted) and which are refused (running, paused, blocked) with the error name run_not_filable, plus the timing advice 'file it when it finishes'. It also covers the when-not path: filing into the current project is a no-op, and a cross-project move requires move: true.

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. The description adds no behavioral context beyond this, saying nothing about result ordering, size, or what a 'link' means (wikilink, mention, etc.).

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, appropriately sized for a one-parameter read tool. It is lean bordering on terse, 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 simple read tool with a fully documented single parameter and rich annotations, the definition is minimally sufficient. However, it omits the return shape and result limits, and there is no output schema to compensate.

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

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

Schema description coverage is 100%, so note_id is fully documented in the schema itself, including where to source ids (search_notes, list_notes, read_many). The description adds no meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (notes that link to the given note), which is functionally distinct from siblings like list_notes or search_notes. It does read as an inverse-link query, but it does not explicitly name or contrast with any sibling alternative.

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 and no mention of alternatives such as search_notes or read_many. The agent can only infer applicability from the phrase 'the given note'.

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 phrase 'most-connected' adds a useful ordering hint that the annotations cannot convey, but the description says nothing about what 'hub' means, how connections are counted, or how ties are broken.

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 zero filler, and the key concept (most-connected hubs) comes first. It is appropriately sized for the tool, though it could have spent one clause on ordering or limit behavior without becoming bloated.

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

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

With no output schema, the description must carry the return-value burden, and it only indicates that results are notes ordered by connectivity. It omits what fields come back, what counts as a 'hub', and pagination behavior, leaving real gaps for a discovery 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 100% for the single 'limit' parameter (type, default 20, min 1, max 100), so the schema fully documents it. The description adds no extra parameter meaning such as ordering interaction with the limit, so the baseline of 3 applies.

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

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

The description pairs a specific verb (list) with a specific resource (hub notes) and a scope qualifier (most-connected, in the vault). It is distinguishable from generic siblings like list_notes or search_notes, though it never explicitly contrasts itself with them.

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

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

There is no when-to-use guidance and no mention of alternatives such as list_notes, search_notes, or get_backlinks, which all surface note-related results. An agent must infer that this tool is for discovering highly-linked notes rather than querying them.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds useful context (workspace-scoped, browser-lane, intended for customer-owned agents) but says nothing about pagination, result volume, or ordering, which is the kind of detail that would push this higher.

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 resource front-loaded and no filler. Every clause earns its place.

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

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

For a two-parameter, optional-filter list tool with full schema coverage and annotations covering safety, the description is nearly complete. Leaving "browser-lane" undefined and not mentioning the available filters keeps it from a 5.

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% (run_id and status are both documented, with status enum values), so the schema carries parameter meaning. The description adds nothing about the two optional filters, so baseline 3 is appropriate.

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

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

States a specific verb+resource ("List browser-lane escalations") and scopes it to the workspace, which distinguishes it reasonably well from action siblings like claim_escalation and resolve_escalation. It stops short of explicitly contrasting itself with those siblings, but an agent can infer read vs. act.

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 clause "so a customer-owned agent can resolve them" implies the intended workflow (read before acting) but never states when to use this versus claim_escalation, resolve_escalation, or abandon_escalation, nor any exclusions. Usage is only implied, not specified.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world semantics, so the safety bar is met without prose. The description still adds real value beyond them: it discloses that bodies are excluded ('no bodies') and that results are unranked, which shapes agent expectations. Pagination/return-shape detail is absent, keeping it short of a 5.

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

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

Front-loads the core purpose and the scoping rule before the alternative and the example. Dense but nearly every clause earns its place; the trailing example is useful but slightly long relative to the rest.

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

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

With no output schema, the description carries the burden of describing returns, and 'note metadata (no bodies)' plus the read_many follow-up covers the essential shape. For a 6-param, zero-required listing tool this is complete enough, though it could say more about result ordering/paging.

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

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

Schema description coverage is 100%, so every parameter including the mutual-exclusion caveats (tag vs project) is already documented in the schema. The description's example ({"project":…,"sort":"updated","limit":20}) illustrates a valid combination but adds no semantics beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Browse note metadata (no bodies)') and immediately bounds the scope, explicitly naming the sibling it is not ('use search_notes — this endpoint does not rank'). An agent can distinguish this from search_notes and read_many without opening any schema.

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

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

Gives a clear when-to-use condition ('when there is nothing to search for'), an explicit when-not plus the alternative ('When you DO have a question, use search_notes'), and the natural follow-up ('Follow up with read_many'). This is the full when/when-not/alternatives triad.

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 adds real behavioral context beyond that: the default status is active, the returned fields, and the fact that the id can be reused as `project`/`project_id` in other tools. It does not discuss pagination or result limits, which is the only notable gap.

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

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

Front-loads the trigger condition, then the return shape, then the routing to sibling tools, ending with a concrete example. Dense but every sentence carries routing or scoping information; the only minor redundancy is repeating the status default already in the schema.

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

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

An output schema exists so return values need no prose, and annotations carry the safety profile. The description covers the trigger, the scoping semantics of the returned id, and the default filter, which is everything needed to call this correctly.

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

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

Schema coverage is 100% and the single enum parameter is fully documented with its default in the schema. The description's '`status` defaults to `active`' merely restates the schema default, adding no new syntax or semantics. Baseline 3 is appropriate when the schema does the work.

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 ('Lists this workspace's projects') and enumerates the returned fields (id, name, status, counts, scope_tag). It also defines what a project is and how it relates to runs/notes, which cleanly separates it from siblings like list_runs or list_notes.

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

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

Explicitly says 'Start here when a request names a topic, client or workstream' and names the downstream alternatives (search_notes, list_notes, list_runs, start_run) with the condition that selects them. It also names create_project for the no-match case, so the agent knows both the entry point and the fallback.

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/idempotent/non-destructive/closed-world, so safety is covered. The description adds non-obvious behavioral nuance: that certain tiers can no longer be STARTED yet their finished runs persist in the vault, which meaningfully affects interpretation of results. Pagination behavior is omitted but cursor is documented in schema.

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

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

Purpose is front-loaded, followed by parameter clarifications in a logical order. Dense but each clause carries meaning; only minor redundancy with 'premier = Deep' appearing again in the schema.

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

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

For a read-only list tool with no output schema, 100% schema coverage, and zero required params, the description covers the semantic quirks an agent needs. Return field shape is not described, but no output schema exists to defer to, leaving a small gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further — explaining that project_id 'none' means unfiled, that status accepts comma-separated values, that tier is a historical filter accepting deprecated-start tiers, and that 'premier' surfaces as 'Deep'. That is genuine value beyond the schema text.

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

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

States a specific verb (list) and resource (research runs) with a scoping qualifier ('that accumulated evidence in this workspace vault'). It is clearly distinguishable from siblings like run_status (single run) and list_projects/list_notes/list_sources (different resources).

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 filtering semantics imply how to narrow results, but there is no explicit 'use this when' guidance or an alternative named (e.g., run_status for a single run). A reader has to infer that this is the multi-run enumeration tool.

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

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

Annotations already establish the safe read-only, idempotent, closed-world profile, so the bar is lower. The description adds real context beyond them: licensed sources carry a `licensed` object with provider, licence type and price, and it points to the endpoint that defines licensable publishers and the per-article cap.

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 before the licence aside. The second sentence is information-dense but every clause earns its place by explaining the `licensed` field and the licensing endpoint.

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 partially compensates by describing the `licensed` sub-field. However, it says nothing about pagination or what the overall result set looks like despite a `limit` parameter, leaving a meaningful gap for a list 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 100%, so both `limit` and `domain` are fully documented in the schema. The description only restates domain filtering ('optionally by domain') and adds no syntax or semantics beyond what the schema already provides; 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?

Specific verb ('List') plus resource ('fetched sources') with a scope modifier ('optionally by domain'). It is clearly distinguished from sibling fetch_url (which acquires) and check_source (which inspects one), though it never names those siblings 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?

Usage is only implied: 'optionally by domain' hints at the filtering case, but there is no guidance on when to use this versus check_source or scholar_search, and no listed prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds what the schema cannot: fetched web bodies arrive wrapped in <untrusted-source> delimiters with an explicit treat-as-data-not-instructions directive. That is genuine prompt-injection guidance, not a restatement of 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?

Front-loaded with purpose and the 50-note limit, then routing, then a disambiguation warning, then the injection note. Every clause carries information; the inline example is compact and earns its space.

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

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

For a single-parameter batch read with no output schema, the description supplies the batch ceiling, the sequencing with search_notes, the id-namespace trap, and the trust framing of returned content. Nothing an agent needs in order to call it correctly and interpret its output safely is missing.

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

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

Schema coverage is 100% and the single parameter is already documented (max 50 ids), so baseline is 3. The description adds real semantic value beyond the schema: the ids should be the search hits the agent intends to quote or cite, a concrete example pair is given, and it clarifies which id namespace is valid (note ids, not run_ids).

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 with scope ('Read up to 50 notes in one call') and explicitly distinguishes itself from read_note by contrast ('rather than reading them one at a time') and from search_notes by sequencing ('the normal follow-up to search_notes'). An agent can tell it apart from all 28 siblings without opening a schema.

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

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

Explicit when-to-use ('follow-up to search_notes'), explicit what to pass ('the ids of the hits you intend to quote or cite'), explicit what-not-to-do ('A report hit is NOT a note id'), and it names the alternative tool to use instead ('send its run_id to run_result'). Exclusions and routing are both covered.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real value: it flags that fetched web bodies come wrapped in <untrusted-source> delimiters with instructions to treat them as data, and it identifies the `source` field as the citation URL. Error behavior and size limits are undisclosed, keeping it short of a 5.

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

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

Purpose is front-loaded, followed by routing guidance, an example, and a security caveat, in that order. Four tight sentences with no repetition or 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?

No output schema exists, and the description compensates by describing the return shape (frontmatter, body, oa block, source citation field, untrusted-source wrapping). For a one-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

With 100% schema coverage and a single param, baseline is 3; the description adds a concrete example invocation ({"note_id":"eu-ai-act-enforcement-2026"}) that demonstrates the expected id format and its provenance from a search_notes hit. It goes slightly beyond the schema without re-documenting constraints like min/max length.

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

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

States a specific verb+resource ('Read one vault note in full') and enumerates what a read returns (frontmatter, body, the oa block). It distinguishes itself from the sibling read_many by scope (single id vs several), so an agent can pick correctly without opening either schema.

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

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

Explicitly says when to use it ('a single id from a search_notes hit') and names the alternative with its tradeoff ('for several, read_many is one call instead of N'). This is exactly the when/alternative guidance the dimension asks for.

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=false, destructive=false, openWorld=true, so the mutation profile is covered; the description adds materially new context by flagging that the call is billable and that retries charge again unless the idempotency key is reused. It stops short of saying what happens to the original run's prior outputs or how to observe the new run.

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

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

Two sentences, zero filler, with the core action and its billing implication front-loaded before the retry hint. 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?

There is no output schema, so the description carries the burden of return-value disclosure and omits it — an agent cannot tell whether it receives a new run_id to poll or a job handle. It also silently leaves the deprecated budget/levers sub-fields to the schema, which is acceptable but leaves the kickoff-to-observation workflow incomplete.

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%, including the step pattern, run_id format, and the idempotency-key semantics, so the baseline is 3. The description restates the idempotency key but adds no syntax, format, or interaction detail (e.g. step format, deprecated budget/levers fields) beyond the schema.

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

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

States a concrete verb+resource+scope: 'Create a billable rerun starting at a named pipeline step.' The 'starting at a named step' qualifier distinguishes it from a fresh start, though it never names the natural alternative (start_run) the way the clearest sibling pairs do.

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 an idempotency key for safe retries' is a calling tip, not when-to-use guidance. There is no statement of when to rerun_from versus start_run, control_run, or simply polling run_status on the existing run, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the 'must be claimed first' state nuance and marks the raw artifact as optional, but never explains the effect of resolving (e.g. that note fields like tags/summary are persisted, or what happens to the escalation afterwards). With annotations lowering the bar, this is an acceptable but not rich 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?

A single tight sentence with no filler, and the core action is front-loaded. It is arguably too compact for a 7-parameter mutation tool, but there is zero waste.

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

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

With 7 parameters, no output schema, and only hint-level annotations, the description carries more burden than it meets: it omits what resolving actually produces (apparently a note with tags/summary/title) and any permission or lifecycle context. It is adequate for a correct call but not for understanding the outcome.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, giving a baseline of 3. The description reinforces only two of the seven parameters (body, raw_r2_key) and adds no format or constraint detail beyond what the schema states.

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 (resolve an escalation) and identifies the two inputs that characterize the operation: extracted body text plus an optional raw artifact key. It is clearly distinguishable from claim_escalation and abandon_escalation, though it never names them. The odd phrase 'customer-extracted text' is slightly less clear than the schema's 'page text you extracted', but the intent survives.

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 word 'claimed' implies the precondition that an escalation must first be claimed (presumably via claim_escalation), which is useful implied guidance. However, there is no explicit statement of when to resolve vs abandon, nor when a raw artifact is worth uploading. Usage is only inferable.

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, idempotentHint, and destructiveHint=false, so the safety profile is already covered. The description adds valuable context beyond annotations: the report part is truncated to 20,000 characters with a one-hour signed URL. But it doesn't explain behavior for other parts (e.g., whether they are paginated or truncated), so it's not fully transparent.

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 dense sentences: the first front-loads the purpose and enumerates parts with special behavior, the second explains run_id origins and gives an example. Every clause earns its place with no waste.

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 read-only tool with full schema coverage and annotations covering safety, this description is nearly complete. It covers the key behavioral quirk (report truncation and signed URL), tells where run_id comes from, and gives an example. It could be slightly richer by clarifying behavior for non-report parts, but no output schema is needed.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description repeats the part values and mentions the run_id sources, but doesn't add syntax or format details beyond what the schema provides. With full schema coverage, the baseline is 3.

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

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

The description states a specific verb ('Read') and resource ('one part of a finished run's result'), then enumerates the exact part values. This clearly distinguishes it from siblings like run_status (status, not result) and verification_result (verification, not the full run result). An agent can tell exactly what this tool returns without opening the schema.

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

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

The description tells the agent where run_id comes from (search_notes report hit, list_runs, start_run), which is essential context for when and how to invoke it. However, it doesn't explicitly state when NOT to use it or contrast it with alternatives like run_status or verification_result, 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context about what the view contains (counters, spend, escalations), which goes beyond annotations, but it does not describe freshness, polling behavior, or error cases.

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

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

The first sentence is front-loaded and efficient. The second sentence about `tier` names and legacy values is lengthy and disconnected from the actual single-parameter signature, spending words on information an agent cannot act on.

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

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

With no output schema, the description usefully enumerates the fields the view returns, which is the main completeness win. But for a simple read-only status tool it omits any guidance on polling cadence or how it relates to run_result/list_runs, and the stray tier discussion is irrelevant noise rather than completion.

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

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

Schema description coverage is 100% and there is only one parameter (run_id), which the schema already documents fully with source hints (start_run, list_runs, search_notes). The description adds no parameter detail and instead introduces a `tier` concept that is not a parameter at all, so it neither helps nor compensates.

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 first sentence gives a specific verb and resource and enumerates the returned view (status, current step, progress counters, spend, escalations), which clearly separates it from run_result and list_runs. However, the second sentence discusses a `tier` id and values like Light/Deep/`premier`/`brief`/`full`/`dissertation` that do not correspond to any parameter in the schema, muddying an otherwise clear statement of purpose.

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

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

There is no explicit when-to-use guidance. With siblings like run_result, list_runs, and control_run, the agent must infer that this is the lightweight status-poll tool rather than a result fetcher. No alternatives or exclusions are named.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and non-idempotence. The description adds the metering/pricing trait, which is genuinely useful context beyond the annotations, but it does not explain the unusual readOnlyHint=false for a search nor disclose anything about rate limits or quota-exhaustion 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 short parenthetical sentences, zero filler, with the core capability front-loaded and the metering caveat last. 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, listing the returned fields (DOI, venue, citation counts, retraction flags) is the right compensation, and the metering note covers the cost dimension. It could still say a bit more about result limits/pagination and the DOI single-lookup mode, but the essentials are present.

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

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

Schema description coverage is 100%, so query, doi, and limit are fully documented in the schema. The description only reinforces the payload fields and hints at DOI lookup; it adds no syntax, format, or behavioral meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Search) plus resource (scholarly works) and enumerates the return payload (DOI, venue, citation counts, retraction flags). It is clear what the tool does, but it never names a sibling such as verify_citations or check_source to route the agent among the other scholarly 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?

"Metered after the monthly free allowance" warns about cost but gives no when-to-use, when-not-to-use, or alternative-selection guidance. Nothing tells the agent whether to prefer this over verify_citations, check_source, or search_claims.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds useful behavioral context beyond that: results are claims paired with an attributed quotation, and scoping is possible via run_id. It stops short of describing ranking, pagination, or empty-result 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 tightly packed sentences plus a compact example. Core purpose leads, routing guidance follows, and no sentence is redundant.

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

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

There is no output schema, so the description carries the burden of describing return values — and it does ('each with the quotation that supports it', attributed quotes). Combined with routing guidance and a usage example, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top: query should be phrased as a single factual statement/sentence, and the worked example ({"query":"GPAI obligations apply from August 2026","limit":20}) concretely shows the expected query phrasing and limit usage.

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

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

Names a specific verb+resource ('Search the atomic CLAIMS runs extracted') and immediately defines what a claim is (a factual statement plus its supporting quotation). It distinguishes itself from the closest sibling, search_notes, by contrasting statement-level vs topic-level search.

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 states when to use it ('check whether one specific factual statement is already evidenced'), when to use the alternative ('Use search_notes instead when the question is a topic rather than a statement'), and the follow-up path ('follow a claim back with read_note for its context'). It also names the narrowing condition for run_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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds real value beyond that: the hybrid bm25+embeddings retrieval behavior, the default-on report inclusion, and the untrusted-source injection warning about wrapping fetched web bodies in `<untrusted-source>` delimiters. No pagination or rate-limit detail, which keeps it short of a 5.

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

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

Front-loaded with the purpose and the key behavioral instruction ('send a whole question, not keywords'), and the example object is compact. It is a dense single paragraph packing scope, workflow and a security note; slightly long but almost 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?

No output schema exists, and the description compensates by explaining what hits contain (`kind`, `run_id`, `source`) and what to do with them (read_many, cite, run_result). For a 12-parameter search tool, this covers everything an agent needs to select and invoke it correctly.

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

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

Schema description coverage is 100%, so every one of the 12 parameters is already documented, including the `tag`/`project` mutual exclusion and the `project` id format. The description reinforces the scoping vocabulary and gives an example object, but adds no semantics the schema lacks — baseline 3 is appropriate.

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

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

States a specific verb and resource ('Search this workspace vault') and immediately narrows scope to evidence notes plus finished reports as `kind: "report"` hits, distinguishing it from list_notes, search_claims and scholar_search. An agent can tell what corpus is searched and what a hit looks like without opening the schema.

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

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

Gives explicit operating guidance: send a whole question rather than keywords, which facets to scope by, how to obtain project ids (list_projects), and the downstream workflow (read_many the top ids, cite each `source`, pass `run_id` to run_result for report hits). This routes the agent through alternatives rather than leaving inference.

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

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

Goes well beyond the annotations: it discloses that the call is billable with concrete tier prices, that an unsupported tier is refused with 400 tier_not_offered, that idempotency_key makes retries safe, and the side effects of filing (source reuse and `project:<id>` tagging) versus unfiled runs. This is rich behavioral context the annotations alone do not provide.

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

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

Dense but well front-loaded: the core action, return value and billing lead, followed by tier choice, tracking, project filing and parameter notes. It is longer than most definitions but nearly every sentence carries actionable information; a slightly tighter grouping of the deprecated-parameter notes would help.

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

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

For a mutation tool with 8 parameters, nested objects and no output schema, the description covers billing, error behavior, follow-up tools, project filing semantics and deprecated parameters. Nothing an agent needs to invoke it correctly appears to be missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that levers shape wording only and never price/sources/run time, explains the default tier, and tells the agent that budget.* and two levers are deprecated but still accepted. That is more than restating field docs.

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 ('Start a hosted deep-research run and return its id immediately'), and its scope is clearly distinguished from siblings like run_status, run_result, list_runs and file_run. An agent can tell exactly what this tool does without opening the schema.

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

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

Explicitly names alternatives and the conditions that select them: use run_status to track and run_result when done, call list_projects (then create_project) before filing work under a project, and use file_run for an already-started run. It also says when to pick premier over the default light.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the risky/mutating nature is covered structurally. The description adds only the list of mutable fields, without stating permission requirements or that summary/tag edits overwrite existing data (that detail lives in the schema, not the description).

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 resource and the mutable surface come first and every word 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 the safety profile is covered by annotations and all five parameters are fully described in the schema, so nothing critical is missing. However, the description never states that updates are partial (only supplied fields change) or what happens on an unknown note_id, leaving modest gaps.

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

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

Schema description coverage is 100% and each of the 5 parameters is documented in the schema, so the baseline of 3 applies. The description merely mirrors the schema's field list and adds no extra syntax, format, or constraint detail.

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

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

States a specific verb (Update) and resource (a note), and enumerates the mutable dimensions (status, tags, summary). It is distinguishable from siblings like create_note and read_note, though it does not explicitly name the boundary between 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?

There is no explicit when-to-use guidance, no exclusions, and no named alternative (e.g., 'use create_note for new notes; this only modifies existing ones'). Usage is only implied by the verb.

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/no-open-world, so safety is covered. The description adds genuinely non-structured behavior: that completed exports yield a short-lived download URL, which tells the agent to re-poll and to consume the URL promptly.

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, no filler, with the core action front-loaded and the output caveat 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 one-parameter status-poll tool with no output schema, the description covers the essential return behavior (download URL on completion). It stops short of describing non-terminal states or whether import jobs ever produce a URL, but nothing blocking 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?

Single parameter with 100% schema description coverage; the schema already explains job_id and its provenance ('returned by export_vault or fetch_url'). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb ('Poll') and resource ('vault import or export job'), which cleanly separates it from the sibling vault_status (vault-level) and run_status (run-level). The second sentence adds the distinguishing scope detail that finished exports carry a download URL.

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 'poll' — it is the tool you call repeatedly to track an async job — but no alternative is named and no when-not condition is given (e.g. use vault_status for overall vault state). Adequate but leaves 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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by enumerating the concrete contents of the response and by implying the authentication requirement ('Authenticated workspace identity'), which the annotations do not express.

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 core payload and followed by a single actionable routing cue. Every clause earns its place with no padding or repetition of the title.

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

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

With no output schema, the description must carry the return-value burden, and it does so by naming the data categories returned. 'Health' is left somewhat vague as to what conditions constitute unhealthy, which is the only real gap for a zero-param, read-only diagnostic 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema shows. Baseline of 4 applies; no parameter-level semantics are missing.

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 and what it returns: authenticated workspace identity plus vault counts and health broken down by notes/sources/projects/last sync. It is clearly distinguishable from the list_* siblings because it is an aggregate status rather than an enumeration, though it does not name those siblings as contrasts.

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 (orientation/health check) rather than stated. The one explicit guidance sentence — a non-zero `projects` means list_projects has scopes worth searching — routes the agent to a downstream tool but does not say when to call vault_status itself or when to prefer it over list_notes/list_projects directly.

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 readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: the result is 'terminal,' 'standalone,' and includes a 'short-lived download URL,' which signals expiration. It does not mention authentication or rate 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?

The description is a single, front-loaded sentence that communicates the action, the result type, and an important return characteristic without any wasted 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 one-parameter read-only tool with full schema coverage and annotations, the description is nearly complete. It states what is returned (receipt and short-lived download URL) even though there is no output schema, though it could better relate this tool to verification_status or verify_citations.

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

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

Schema description coverage is 100%, and the single parameter verification_id is documented in the schema as 'A verification id returned by verify_citations.' The description adds no further parameter syntax or constraints, so the baseline 3 is appropriate when the schema carries the semantics.

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

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

The description states a specific verb and resource: 'Get a terminal standalone verification receipt.' The qualifiers 'terminal' and 'standalone' and the mention of a 'short-lived download URL' make the purpose clear, but it does not explicitly distinguish itself from the sibling tool verification_status.

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 word 'terminal' implies the tool should be used after a verification has reached a terminal state, and the mention of a receipt implies when a downloadable record is needed. However, there is no explicit guidance about when to use this versus verification_status or verify_citations, 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is fully covered. The description adds only that it returns status plus metered pair counts; it says nothing about polling cadence, terminal states, or whether counts are cumulative.

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 tight sentence with the resource front-loaded and no filler. It could drop 'current' but there is essentially no waste.

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

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

For a simple read tool with annotations handling safety, this is close to adequate, but with no output schema the description never characterizes the status values or the shape of 'metered pair counts', leaving the agent to guess what it will receive.

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

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

One parameter at 100% schema coverage, so the schema fully documents verification_id including its origin and length bounds. The description contributes no additional parameter meaning, which matches the baseline of 3 for fully-covered schemas.

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

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

States a specific verb+resource ('Get the current status ... for a standalone verification') and even names the returned payload ('metered pair counts'). It distinguishes itself reasonably from verify_citations (which initiates) but not from the sibling verification_result, leaving the status-vs-result split 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?

Usage is only implied: the schema note that verification_id comes from verify_citations suggests this is the follow-up/polling call, but the description never says when to use this instead of verification_result or how long to wait. No when-not guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the bar is lower. The description still contributes real context the annotations do not: the operation is metered/billed and it hands back a verification id rather than results, which tells the agent this is a paid, asynchronous kick-off rather than a synchronous answer.

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 core action and immediately followed by the return contract. The only minor waste is '(metered)' appearing in both the title and the description body.

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 five-parameter, metered, asynchronous job with no output schema, the description omits the natural next step: that the returned id must be polled via verification_status and read via verification_result. The agent can guess this from the sibling names, but the description does not close the loop.

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

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

Schema description coverage is 100% and all five parameters carry their own documentation (sample modes, source shape, idempotency_key retry semantics, markdown input). The description adds nothing parameter-level beyond what the schema already states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Verify citation-sentence bindings in a document against sources') and adds the return contract ('Returns a verification id'), which implies the async split from the sibling verification_result / verification_status tools. It never names those siblings explicitly, so the differentiation is inferred 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?

There is no when-to-use guidance, no exclusion criteria, and no mention of the obvious alternatives (check_source for a single source, verification_result / verification_status for retrieving the outcome). The only usage signal is the parenthetical '(metered)', which hints at cost but not at routing.

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