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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotent=true, destructive=false, but the description adds substantial context beyond them: external HTTP calls, no API key needed, knowledge-base cache returned before an outbound fetch, auto-indexing with content-policy flag/block behavior, and [OK]/[ERROR] envelopes with remediation. The only minor gap is it doesn't caveat that 'idempotent' can be undermined by live page changes, and the content-policy details are deferred to infobroker_manage_kb.

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

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

Purpose is front-loaded in the first clause, followed by usage routing, then parameter behavior, then behavioral caveats. It is dense and backtick-heavy, packing many clauses per sentence, but nearly every sentence carries distinct information; slight tightening would improve readability without losing content.

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

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

For a 9-parameter, no-output-schema, network-touching tool, the description covers the important gaps: return envelopes, error handling, caching, and KB side effects. It relies on a pointer to infobroker_manage_kb for policy details rather than explaining them, and the shape of 'results' and 'meta' within the [OK] envelope is left implicit, which keeps it one step shy of complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine value: the interaction between question/passage_size/max_passages, the crawl config caps, what extract returns, and the operational reason to pick native_fetch (keyless fallback when Jina is throttled or anti-bot challenged). It also clarifies that max_length truncates only the returned text and that the full page is written to a temp file. It omits any mention of detect_date, which keeps it from a 5.

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

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

States a specific verb and resource ('Fetch a URL and extract clean content') plus the renderer backends, and explicitly distinguishes itself from infobroker_search_web and infobroker_verify_claims. An agent can identify this as the single-URL content retrieval tool without opening the schema.

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

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

Gives an explicit use condition ('when you have a URL and need readable text, passages ranked against a question, or the page's last-updated date') and explicitly names two anti-cases with the sibling tools to use instead. This is the when/when-not/alternative pattern at full strength.

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, openWorld, and non-destructive, but the description adds behavior they cannot express: no API key required when a scholarly source is reachable, per-provider rate limits, and an [ERROR] envelope with remediation when every source fails. This is meaningful operational context for a read tool.

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

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

Front-loaded with purpose, then usage rules, then parameter and failure behavior — a sensible ordering. It is dense (four sentences covering a lot), but every clause carries distinct information rather than restating 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?

No output schema exists, yet the description still specifies the return format (BibTeX fields) and the envelope contract ([OK]/[ERROR] with remediation). For a two-parameter, read-only 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?

Schema coverage is 100%, so the baseline is 3, and the description earns extra credit by clarifying that `query` is a natural-language topic and that larger `max_results` values 'take longer and span more sources' — a latency/coverage tradeoff the schema does not state.

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 academic references for a query') plus the exact output shape (BibTeX with title, authors, year, venue, URL). An agent can distinguish this from search_web and verify_claims without opening any schema.

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

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

Explicitly names the trigger ('when scholarly writing needs a reference list') and two exclusions with the sibling to use instead (infobroker_search_web for general web search, infobroker_verify_claims for contested-claim verification). Nothing is left to inference.

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

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

Beyond the readOnlyHint/destructiveHint annotations it adds operative facts: it never modifies configuration or stored data, `health` is a live outbound probe subject to the provider's rate limits and 'can be slow', and `provider` is required for that action. It also discloses the [OK]/[ERROR] JSON envelope, which annotations cannot convey.

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

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

Front-loaded with the core purpose and organized use-case → anti-use-case → semantics → return shape, with no filler sentences. It is dense and heavily backticked, which makes it slower to parse than necessary, but every clause carries information.

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

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

There is no output schema, and the description closes that gap by describing the return envelope and the result fields (status, provider, results). For a three-parameter, read-only inspection tool, an agent has everything needed to call it correctly and interpret slowness on `health`.

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%, but the schema descriptions are near-useless ('Operation to perform'), and the description compensates by explaining what each action does ('list' snapshots, 'status' filters it, 'health' probes, 'spec' reports identity). It stops short of explaining the 'active'/'all' enum values, so a small semantic gap remains.

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 clause names a specific verb and resource ('Inspect configured search providers') and enumerates the three sub-behaviors (state, health check, build/spec identity). It explicitly distinguishes itself from infobroker_search_web and infobroker_fetch_page, so an agent can route 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 a concrete trigger ('when searches return empty or slow results', 'choosing which backend to trust') and explicit negative routing ('Do NOT use to search... or to read a page') naming both alternatives. This is the when/when-not/alternatives pattern at full strength.

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 it pinpoints which action is destructive ('delete ... cannot be undone') and discloses a non-obvious irreversibility (lost encryption key makes the store unrecoverable by design), plus the [OK]/[ERROR] response envelope and per-action return shapes. It does not address re-ingest idempotency or duplicate handling, which matters given idempotentHint=false. No contradiction with destructiveHint/openWorldHint.

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

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

Purpose and the use/do-not-use routing are front-loaded in the first three sentences, which is the right ordering for a 9-action multiplexed tool. The trailing 'Parameter semantics:' block is a dense run-on that could be tabled, but every clause carries operational information rather than filler.

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

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

For a 16-parameter, 9-enum, nested-object tool with no output schema, the description covers everything needed to call it: action selection, per-action parameter pairing, destructive and unrecoverable failure modes, and response shape per action. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the cross-parameter mapping the schema lacks, notably which params pair with which `action` (query→search, text/url+title/collection→ingest, source_url→get/delete, operation+key_file→encryption). It also restates defaults (save_to 'kb', format 'markdown', max_results 8) and the last_updated auto-detection rule, though most of this duplicates existing schema descriptions.

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

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

The description opens with a specific verb+resource ('Manage the local knowledge base') and then enumerates the concrete operations (search, ingest, list/get/delete, stats, claims, encryption). It explicitly separates itself from the siblings infobroker_search_web and infobroker_fetch_page, so an agent can route without opening any schema.

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

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

It gives an explicit trigger ('Use when you need to archive a generated report... or manage encryption keys') including the exact parameter combination (source_type 'report' + save_to 'kb'), and explicit exclusions naming the two alternative tools for fresh search and page fetch. When-to-use, when-not, and alternatives are all present.

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

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

Goes well past the annotations (destructiveHint=true, idempotentHint=true, openWorldHint=true) by disclosing the write/merge sequence: deep-merge into config.local.json, rejection of unknown top-level keys, backup of the previous layer, validation before writing, migration ordering, and the failure semantics (invalid config leaves the previous config active and returns an error). It also names the response envelope. It does not mention auth requirements or whether the backup file location is exposed, which keeps it below a 5.

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

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

Front-loaded with purpose, then usage routing, then behavioral detail; every sentence conveys a distinct fact and none is filler. It is dense (long semicolon-chained clauses) and slightly heavy for a two-parameter tool, but the mutation risk justifies the depth.

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?

Despite having no output schema, the description states the return contract ([OK] or [ERROR] JSON envelope), covers the failure path and rollback behavior, and describes both parameters' effect on disk state. Nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: patch is defined as a deep-merge into the user layer with unknown-key rejection and pre-write validation of the merged result, and migrate is described in terms of backup plus registered migration application ordered 'before reloading'. That ordering and validation detail is not in the schema descriptions.

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

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

Specific verb (re-read/apply) plus resource (configuration file) and the exact classes of changes applied (provider, rate-limit, knowledge-base) with the key constraint 'without restarting; active connections are preserved'. It also differentiates itself from the sibling infobroker_inspect_providers, so an agent can route 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?

Explicit trigger ('Use when you have edited config.json or config.local.json, or when passing patch'), an explicit exclusion ('Do NOT use to inspect configuration or provider state') and the named alternative to use instead. Both the positive and negative conditions are stated, not 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 only declare read-only, idempotent, non-destructive, open-world. The description adds material facts the agent cannot infer: results are cached in the local knowledge base (so results may be stale unless fresh:true), per-provider rate limits are enforced, free providers need no API key, and every response is an envelope prefixed [OK]/[ERROR] carrying status, provider, results, and meta.

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

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

Three sentences, front-loaded with capability, then exclusions, then behavior — a sound order with no filler. However, the second sentence is an extremely dense parenthetical list of eight modes, and the exclusions are packed into one long sentence, making it harder to scan than a short bulleted structure would be.

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

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

For a 16-parameter tool with no output schema, the description supplies the pieces an agent actually needs: what the modes do, when to pick a sibling instead, that caching can make results stale, that rate limits exist, and the shape of the return envelope. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes slightly beyond it by explaining the operating modes (suggest, expand, deep, research, analyze) and the meaning of fresh:true in the context of the KB cache. It does not cover the remaining routing knobs (priority, region, language, time_range, content_type, max_results, page), which are left entirely to the schema.

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

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

States a specific verb (search) and resource (web, encyclopedia, academic, code sources) plus the unifying mechanism (one interface, automatic provider selection, fallback chain). It then enumerates the distinct modes — suggest, expand, deep, research, analyze — so an agent can tell this apart from infobroker_fetch_page and infobroker_verify_claims without opening any schema.

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

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

Explicitly names when to use it (broad or batched search, autocomplete, expansion, ranked passages, research compile) and four when-not cases each paired with the correct sibling tool ('Do NOT use for a URL you already have (use infobroker_fetch_page)... for academic citations (use infobroker_get_citations)'). This is the strongest possible routing guidance.

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

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

Annotations only flag readOnlyHint=false, openWorldHint=true, idempotentHint=false; the description goes well beyond them by disclosing the actual write-back loop ('searches providers and writes findings back'), the KB recall step, per-provider rate limits, and the max_iterations refinement bound. It also explains how below-threshold findings are downgraded to 'unverified', which no annotation conveys.

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

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

Purpose and use/do-not-use guidance are front-loaded, and the operational detail follows in a single dense block. It is long, but nearly every clause contributes routing or behavioral information; a little trimming of overlapping phrases would make it tighter.

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 supplies the return contract — an [OK]/[ERROR] envelope listing confirmed, contested, and unverified findings with per-source claims and confidence scores. Combined with the loop/rate-limit notes, an agent has everything needed to invoke and interpret the tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the field docs: providers 'omitting it uses the full dispatch chain', priority routing intents (speed, quality, privacy, free_only), and that confidence_threshold determines which findings are reported unverified. max_iterations and query get less added meaning.

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

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

The description states a specific verb and resource — 'Verify a contested claim against independent sources and return confidence-scored findings' — and immediately separates this tool from infobroker_search_web (broad search) and infobroker_get_citations (citation formatting). An agent can distinguish it from every sibling without opening a schema.

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

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

It gives an explicit inclusion condition ('high-stakes or contested') and explicit exclusions with named alternatives ('Do NOT use for simple lookups or broad search (use infobroker_search_web) or citation formatting (use infobroker_get_citations)'). Routing is unambiguous.

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