Geohash

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

Beyond annotations (readOnly, idempotent, openWorld), description adds that default model is free, Anthropic requires a BYO API key with direct payment, and returns per-model details plus combined view.

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?

Concise 4-sentence paragraph with no filler. Front-loaded with main action, then defaults, return format, and use cases. Every sentence earns its place.

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

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

Given 4 parameters (1 required), no output schema, and full schema descriptions, the description adequately explains the tool's behavior, return format (per-model score, confidence, signals, raw_response, combined view), and use cases.

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 description adds default behavior for models, conditional requirement for _apiKey, and clarifies that context helps disambiguate. Adds value beyond 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 clearly states the tool probes LLMs for visibility scoring (0-100) per model, with a specific verb and resource. It distinguishes from siblings like scan_competitor_ai_presence by focusing on quantitative scoring.

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?

Provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model and optional Anthropic with BYO key. Lacks explicit alternatives or when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it explains that Pipeworx routes to the right tool, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. That tells the agent about the response format and citation behavior without conflicting with any annotation.

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?

Extremely information-dense and front-loaded, but the second half of the description becomes a run-on with awkward stitching ('when needed: for a broad/multi-part question...'), and there is some redundancy with repeated examples and routing guidance. Valuable content, but structurally it degrades into a wall of text rather than clean, scannable guidance.

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 1-required-parameter, auto-routing tool with no output schema, the description supplies everything needed: when to use it, what domains it covers, what to expect back (structured answers, citations), and how to decide among close siblings. The alias list in the parameter schema completes the picture for invocation.

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

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

Schema description coverage is 100%, so the schema fully documents the aliases and the main 'question' parameter. The description reinforces that the parameter is a natural-language question and lists example queries, but it doesn't add substantive new parameter semantics beyond what the schema already states. Baseline 3 is appropriate when the schema carries the full 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 is unusually explicit: a single verb ('ask Pipeworx routes the question'), a precise resource ('5,798 tools across 1517 verified sources'), and a clear differentiation from web search and sibling tools like deep_research and ask_pipeworx_grounded. It enumerates concrete domains (SEC, FDA, FRED/BLS, patents, real estate, weather, clinical trials, stocks, sports), making the tool's scope unmistakable.

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

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

Provides explicit when-to-use ('PREFER OVER WEB SEARCH'), trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much'), concrete examples, and names sibling alternatives with the conditions that should route to them ('deep_research for broad/multi-part questions', 'ask_pipeworx_grounded for hallucination-resistant single answers'). This is exactly the kind of routing guidance an agent needs.

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

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

The description adds significant behavioral context beyond the annotations: it discloses that this is an experimental beta, that candidate routing improvements may be enabled or retired, that there is currently no active candidate so it matches the stable version, and that it is a full working router (falls back to nothing). This transparency about its experimental nature and current state is valuable for an AI agent deciding whether to use it.

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

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

The description is information-dense and each sentence adds value: beta status, identical behavior to the stable router, candidate routing state, usage guidance, and fallback behavior. It is slightly long but the length is justified by the complexity of explaining the experimental beta context. The key facts are front-loaded in the first sentence.

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

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

The description covers the essential context an agent needs: what the tool is, how it relates to its stable sibling, the current experimental state, and usage guidance. It doesn't detail the response format, but no output schema exists and the description notes the response shape is identical to ask_pipeworx, which is adequate for a routing tool with a single required parameter.

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 input schema already documents all parameters with 100% coverage, including the five aliases for 'question'. The description adds the semantic context that the same arguments are accepted as ask_pipeworx, but does not explain the parameter format beyond what the schema provides. Since schema coverage is complete, the baseline of 3 is appropriate.

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

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

The description clearly states it is the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. It could be slightly clearer about what 'routing' means, but it does identify the tool's purpose and its relationship to its sibling.

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

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

The description explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. It also clarifies that it currently matches ask_pipeworx exactly since no candidate is active, giving clear guidance on when and how to use this tool versus the stable alternative.

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

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

The description goes far beyond the annotations, disclosing that the tool routes across 5,798 tools, fills arguments, fetches data, extracts only from the tool result, returns a structured success payload, and emits an explicit refusal with specific refusal_reason values. This is highly transparent about what happens and what kind of failure modes exist, with no contradiction to the readOnly/idempotent annotations.

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

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

The description is dense but every sentence earns its place: it opens with the core purpose, explains the mechanism, specifies exact return/refusal shapes, gives concrete use cases, and closes with cost guidance. It is well-organized and front-loaded with the most important 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?

Despite having no output schema, the description fully documents the return shape, refusal reasons, and success fields. It also covers when to use it, why it differs from the sibling, the cost implication, and the kinds of high-stakes scenarios it serves. Nothing essential is missing for an agent to invoke it correctly.

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

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

The description does not elaborate on the question parameter's content or format, but the input schema already covers this fully with a clear description and alias list. With 100% schema description coverage, the baseline of 3 applies; the description adds no extra parameter-level meaning 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?

The description clearly identifies a distinct, grounded answer mode that extracts answers only from fetched tool results, and explicitly contrasts it with ask_pipeworx. It names the resource (Pipeworx tool routing), the verb (answer with grounded extraction), and the behavioral differentiator (refusals when data is insufficient).

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

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

It explicitly states when to use this tool: whenever the answer will be quoted, cited, or acted on and hallucination is unacceptable. It also gives a direct exclusion: prefer ask_pipeworx for casual lookups, and explains the cost tradeoff of one extra LLM call.

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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial detail: market resolution and classification, fan-out logic, response shapes, resolver contract (confidence, alternatives, suggestions), parent event extraction, news fallback, safety blocks for low-confidence/inactive markets, and cancellation rules. No contradictions with annotations.

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

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

The description is very long (multiple paragraphs) with extensive detail. While well-structured with section headings like 'RESOLVER CONTRACT' and 'PARENT_EVENT EXTRACTOR', it is not concise. The length may impede quick parsing by agents, justifying a moderate score.

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

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

Given the tool's complexity (multiple sub-systems, response shapes, edge cases), the description covers all necessary aspects: inputs, behavior, response fields, safety mechanisms, cancellation rules, and error conditions. No output schema is provided, but the response shape is described in detail, making it fully informative 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% with descriptions for all three parameters. The description enriches these: for 'market' it provides examples of slugs, URLs, and question text; for 'depth' it explains the enum values 'quick' and 'thorough'; for 'include_raw' it describes the impact on response size and when to use true. This adds significant meaning 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?

The description clearly states the tool's function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (market slug, URL, or question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like ask_pipeworx (general queries) and polymarket_arbitrage (arbitrage detection), earning top marks.

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 explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly mention when not to use the tool or name alternatives, but the context is clear. A slight deduction for missing exclusions or direct sibling comparisons.

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

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

Annotations already declare read-only and idempotent behavior. The description adds value by detailing what data is pulled (10-K financials for companies, FAERS/trial counts for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and usage examples. Every sentence adds value, covering behaviors, types, and a note on efficiency. It is slightly long but packed with useful information. Minor trimming possible without losing clarity.

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

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

For a tool with 2 parameters and no output schema, the description explains input constraints (2-5 items), data sources, metrics returned, and result format (sorted, with citation URIs). It covers the main use cases adequately. No explicit mention of error handling or limits beyond max items, but sufficient for agent decision-making.

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 meaning beyond the schema by explaining the interpretation of 'type' values (company pulls specific financials, drug pulls safety/trial data) and providing examples for 'values' (tickers for companies, drug names). This enhances the agent's understanding.

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 clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It distinguishes from sibling tools like entity_profile by explicitly preferring it over sequential single-entity lookups and provides query examples (e.g., 'X vs Y', 'rank these companies').

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

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

The description gives explicit usage context: when comparing entities, use this tool instead of sequential lookups. It does not explicitly state when not to use it, but implies that for single entity queries, other tools like entity_profile are appropriate. The guidance is clear but lacks exhaustive exclusion criteria.

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, openWorldHint, idempotentHint, destructiveHint. Description adds 'Keyless, offline' and specifies output details (center coordinate and bounding box), providing context beyond annotations. No contradiction.

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

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

The description is a single, front-loaded sentence that efficiently conveys the purpose, inputs, outputs, and key properties without superfluous 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?

Given the tool's low complexity (one parameter, no output schema), the description sufficiently covers purpose, input required, output format, and operational context (keyless, offline).

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

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

Schema coverage is 100% for the single parameter, which has a description. The tool description does not add additional meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Decode' and the resource 'geohash', specifying outputs (center coordinate and bounding box). It distinguishes from the sibling tool 'encode_geohash' which does the inverse.

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?

Description mentions 'Keyless, offline' implying no special prerequisites, but does not explicitly state when to use this tool vs alternatives or provide exclusion criteria.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the full behavioral contract: parallel facet decomposition, findings packet contents (verbatim evidence, confidence, source, fetched_at, citation_uri), explicit gaps[], contradictions[], never-invented behavior, semantic excerpting, account/paid-plan enforcement, and latency expectations. This is far more than the annotations carry.

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

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

The description is dense and front-loaded with the account gate and alternative before the main behavior, and every major section maps to something an agent needs. However, it's a long single wall of text with parenthetical asides and some repetition of depth semantics already present in the schema, so it's not maximally structured.

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 fully specifies return values (findings packet, gaps, contradictions, hop and citation_uri), access constraints, latency, and edge behavior for long records. Nothing an agent needs to decide or invoke correctly is left out.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents question and depth, including the paid 'thorough' mode. The long description mostly restates depth behavior and adds latency/account context, but doesn't add new field-level meaning 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?

The description states a precise verb+resource: grounded multi-source research across 1,517 structured data sources in one call, and explicitly disambiguates it from open-web search and the ask_pipeworx sibling. It also names best-fit use cases ('broad/multi-part questions'), so an agent can tell exactly when this tool is relevant.

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

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

It gives explicit alternative conditions: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx'. It also states what the tool is best for, plus depth-mode semantics in the schema, making the when-to-use decision unambiguous.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond annotations by noting that results are 'ready to call directly, no second schema lookup needed,' which informs the agent about the tool's immediate usability. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and includes a list of example domains for clarity. It is relatively concise but could be slightly trimmed without losing meaning. Every sentence earns its place, making it structured and informative.

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

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

Given the tool's simplicity and the absence of an output schema, the description fully explains what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples).' This is complete and sufficient for the agent to understand the tool's behavior and output.

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

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

Schema coverage is 100% with detailed descriptions for all 6 parameters. The description mentions that 'query' accepts aliases, which is already covered in the schema. Since the schema does the heavy lifting, the description adds minimal additional semantic value, warranting a baseline score of 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 clearly identifies the tool as a discovery mechanism for finding tools by describing data or task. It lists numerous specific domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes from sibling tools by stating it should be called first to see the option set.

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 provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly states when to use it. However, it does not explicitly mention when not to use it or compare with alternatives, which would strengthen the dimension further.

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 provide safety hints; the description adds 'keyless, offline' meaning no network calls or authentication required, and explains precision's effect on cell size. No contradictions.

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 plus a clarifying parenthetical. Every word is informative; no redundancy.

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

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

For a simple encoding tool, the description is nearly complete. It lacks explicit mention of the return type (string), but that is implicit from the tool name and context.

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

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

Schema covers all parameters with descriptions. The description adds value by explaining precision's range and behavior (more chars = smaller cell), which goes beyond the schema's bare description.

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

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

The description clearly states the tool encodes a latitude/longitude to a geohash string, specifying it's keyless and offline. The sibling 'decode_geohash' confirms distinction as the inverse operation.

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

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

Usage is straightforward: encode coordinates to geohash. The description mentions keyless/offline, implying no external dependencies, but does not explicitly contrast with alternatives or state when not to use it.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, lowering the bar, and the description adds substantial context beyond them. It discloses that an empty section is 'a real "no data", not a bug', that name inputs resolve via SEC EDGAR with resolved_from/resolved_to, and that private companies return resolved:false with a notes line rather than a bare failure. It even flags that small-molecule/generic drug companies will legitimately show zero FDA products, preventing a whole class of agent misinterpretations.

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?

Every sentence earns its place and the most critical routing information is front-loaded in the first two sentences. However, the description runs as one dense ~230-word paragraph with no visual structure, which hurts scannability, and the type-interchangeability note slightly redundantly restates the schema's parameter description.

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

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

For a tool with no output schema and high complexity (7+ sources, multiple return sections, name resolution), the description is remarkably complete: it enumerates every return section, the pipeworx://edgar URI format, the sources_used/sources_failed mechanism, input formats, and expected-empty cases. Nothing an agent needs to correctly interpret the response is left to guesswork.

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; both type and value are fully documented in the input schema. The description restates the type/value interchangeability and repeats the same input examples ('AAPL', '0000320193', 'Moderna') that already appear in the schema descriptions, adding little new parameter-level meaning.

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

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

Opens with explicit natural-language trigger examples ('Tell me about X', 'research Acme', 'give me the rundown on NVDA') and states the core deliverable: 'full cross-source profile of a US public company in ONE parallel call.' The verb+resource is unambiguous, and the 'ALWAYS PREFER... over chaining single-pack SEC/XBRL/news lookups' line clearly differentiates it from adjacent lookup flows.

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

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

Gives an explicit when-to-use directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also scopes when NOT to use it — private companies return resolved:false with a notes line, and 'person/place coming soon' signals the current company-only limitation — though it does not name specific sibling tools like compare_entities or resolve_entity.

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 destructiveHint=true; description adds context about sensitive data and staleness, but does not contradict 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?

Three concise sentences, front-loaded with core action, no redundant 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?

Given annotations and schema fully cover safety and parameters, description provides complete guidance for tool usage including context and pairing.

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 has 100% coverage for the single 'key' parameter. Description adds no additional semantic meaning beyond schema description.

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

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

Description clearly states 'Delete a previously stored memory by key' – specific verb+resource. Distinguishes from siblings by mentioning 'remember' and 'recall'.

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 (stale context, task done, clear sensitive data) and pairs with alternatives (remember and recall).

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe. The description adds process details (fetches page, extracts title/description/key links) that go beyond annotations, enhancing transparency.

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 concise (three sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, process, and use cases. No 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?

Despite no output schema, the description clearly explains the output format ('standard llms.txt markdown format', 'single text blob'). For a two-parameter tool with complete annotations, this is fully sufficient.

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 does not add new parameter semantics beyond what the schema provides (URL and max_links). No further elaboration on parameter constraints or formats.

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 clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on the standard format output.

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 lists explicit use cases (client site indexing, personal projects, competitor audit). While it doesn't explicitly state when not to use or name alternatives, the given scenarios provide strong guidance for appropriate use.

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. Description adds specific return fields and the include_inactive parameter behavior, but doesn't add beyond annotations for safety.

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

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

Two sentences with no wasted words, front-loaded with main function and immediate usage guidance.

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, description explicitly lists return fields. Parameter is covered. Provides complete context for a simple list operation.

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

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

Schema coverage is 100% with a clear description for 'include_inactive'. Description does not add additional parameter meaning beyond schema, 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?

Clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists return fields. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe'.

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 advises use before adding more subscriptions or to find an id to cancel, providing clear context and when-not-to-use.

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

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

The description reveals behavioral characteristics not present in annotations: rate-limiting to 5 per day, free usage, no quota impact, daily digest review, and the claim_token round-trip flow. These are critical operational details beyond what the annotations (all false) could 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?

The description is a single dense paragraph, but every sentence contributes critical information: purpose, exclusions, workflow, rate limits, and free status. It is slightly verbose and would benefit from line breaks, but it is far from wasteful; mild readability deduction.

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

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

With no output schema and annotations revealing nothing (all false), the description carries the full informational burden. It covers purpose, exclusions, claim_token behavior, rate limits, and parameter usage, leaving no significant gaps. It is exceptionally complete for a feedback 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 schema already describes all 4 parameters with 100% coverage, so the baseline is 3. The description adds extra semantics by advising how to frame the message (in terms of Pipeworx tools/packs, avoid pasting end-user prompts) and clarifies claim_token usage context, earning an extra point.

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 ('tell the Pipeworx team') and resource ('something is broken, missing, or needs to exist'), clearly distinguishing it from sibling tools like ask_pipeworx that query data. It also enumerates concrete use cases (bug, feature, data_gap, praise), removing any ambiguity about its role.

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 provides when-to-use and when-not-to-use guidance: it names the trigger conditions and explicitly excludes feedback about tools from other MCP servers. It also explains the claim_token workflow and daily rate limit, leaving no doubt about appropriate invocation.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral details: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h). No contradiction with 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?

Description is 3-4 sentences, front-loaded with main purpose. Every sentence adds value, no fluff. Well-structured and easy to parse.

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

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

Tool is simple (one optional parameter, no output schema). Description explains return type (top tools/packs, call volume) and use context. Complete for the tool's complexity.

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 already describes the 'window' parameter with enum, and coverage is 100%. Description adds slight nuance: 'shorter windows surface hot right now; longer windows show steady-state demand', providing extra context beyond 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?

Clearly states the tool returns trending data (top tools, packs, call volume) from other AI agents, with specific verb 'returns' and resource 'top tools/packs/volume'. Differentiates from siblings like 'discover_tools' by focusing on popularity signal.

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?

Lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking alignment) that guide when to use. Lacks explicit exclusions or alternatives, but context strongly implies appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds substantial behavior: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check against CLOB depth, and details on partition_check. No contradiction with 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?

Description is front-loaded with purpose, then systematically covers modes, filters, and response. Some redundancy but each sentence adds value. Structure is logical for the complexity of the tool.

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, but description details response fields (opportunities, partition_check, fill_check) and edge cases (placeholders, thin legs). Covers all modes and the fill check caveat. Missing some specifics on monotonicity violation context, but sufficient for agent understanding.

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 100% with both parameters described. Description adds meaning beyond schema: explains default behavior when no args, provides concrete examples of event slugs, and describes how topic mode searches related events. Also mentions accepted URL formats.

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?

Description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between default trending_scan, event mode, and topic mode, and contrasts with sibling tools like polymarket_fill_risk.

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?

Provides explicit instructions: call with no args for trending_scan, pass event for specific market, or topic for cross-event scan. Explains when to trade (realizable_edge_pp > 0) and when not to, but does not explicitly exclude alternatives.

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

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

The description thoroughly explains behavioral traits beyond the annotations: caching ('Cached 1h at the KV level'), response structure (by_segment, fed_candidates, _diagnostics), and detailed field explanations (edge_pp_net, kelly_fraction, 24h-move warning). It also describes how filters like min_partition_leg_kelly work and why min_kelly does not affect partition arbs.

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 thorough and well-structured, with clear sections for model families, response fields, and knobs. It is front-loaded with the purpose. However, it is quite lengthy and could be slightly condensed without losing critical 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?

The description provides complete context for understanding the tool's operation and output. It details the response structure, all fields carried by each opportunity, and even includes notes like Fed bets being excluded. Given the complexity (9 parameters, 3 model families, no output schema), the description leaves no 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?

Although schema coverage is 100%, the description adds significant context to each parameter. For example, it explains the rationale behind slippage_pp default, how min_partition_leg_kelly complements min_kelly, and the practical impact of max_spread_pp and min_liquidity. These details provide meaning beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'Scan' and the resource 'Polymarket markets', and distinguishes itself from sibling tools by detailing its unique model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and output structure.

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 explicitly states the tool is 'Built for "what should I bet on today"' and explains how it discovers opportunities without paging through hundreds of markets. It provides guidance on when to use various knobs (e.g., 'Set to 2 to require tight books'). However, it does not explicitly compare with sibling tools or mention when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds substantial context: it reads from daily snapshots, uses daily closes (not intraday), explains missing data meaning, and clarifies that decay numbers come from daily closes of edge_pp_net. No contradictions.

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 long but well-structured: it starts with the core purpose, then details the response shape, and ends with limitations. Every sentence adds value, though some technical details could be slightly more 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?

With no output schema, the description fully explains the response structure (tracked with fields, expired with lifespan, snapshot_dates) and data limitations (60-day TTL, snapshot gaps). Given the tool's complexity (2 optional params), this is very 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?

Input schema covers both parameters with descriptions (100% coverage). The description adds meaning by clarifying defaults (days default 14, window default '1wk'), constraints (days clamp 2-30, window options 24hr|1wk|1mo), and how they affect the response. This goes 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?

The description clearly states the tool's purpose: to answer 'how long has this edge existed and is it shrinking?' and details the outputs (tracked, expired, snapshot_dates). It differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on edge persistence and decay.

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 explains when to use the tool (to distinguish fresh wide edges from old ones) and provides context on data limits (60-day TTL, snapshot start). It does not explicitly state when not to use it or mention alternatives, but the context is sufficient.

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 indicate readOnlyHint, idempotentHint, and no destructive behavior. The description adds behavioral details: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and flags forced_directional_risk. This goes beyond annotations without contradicting them.

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 relatively long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, usage advice). It front-loads the core purpose. Though slightly verbose, every sentence contributes necessary 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?

Given 4 parameters, full schema coverage, and no output schema, the description thoroughly covers all inputs and return values (top_of_book, shares_filled, verdict, per-leg fill detail, thin_legs, etc.). It also warns about partial fills and directional risk, making it complete for a fill-risk checking 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. The description adds significant meaning beyond the schema: it explains the required choice between market (single-market) and event (basket), interprets side defaults and size_usd differently per mode, and clarifies that basket size_usd is settlement notional. This adds valuable context.

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 clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and specifies the tool's role as a risk assessment before executing trades. This is specific and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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 guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why partial basket fills lead to unhedged directional risk, giving clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description goes well beyond this by disclosing matching behavior, compatibility warning semantics, fee treatment (gross spread, no Kalshi fee modeling), unclassified-leg exclusion, temporal alignment null semantics, and per-entry flags. This is rich, non-contradictory behavioral disclosure.

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 long but every sentence earns its place: mode semantics, response contents, safety-field meanings, fee caveats, and skipped-comparison counters are all relevant and clearly labeled. The structure front-loads the core purpose, then moves from modes to response to caveats in a logical order. Dense but appropriately organized for a tool with this many behavioral nuances.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does: venue leg prices, top_spreads_pp, compatibility_codes, temporal_alignment, skipped_unclassified, low_confidence_pairs, fees_note, and skipped counters. It also explains semantic pitfalls like null alignment meaning 'not computed' rather than 'aligned', and why unqualified pairs may still appear. Nothing critical for 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 schema already documents each parameter. The description adds meaningful semantic value by explaining how the parameters interact: 'topic' auto-fetches, explicit values override the mapped side, and both modes run the identical token-overlap matcher with the same disclosures. This goes beyond simple type/value documentation.

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, informative statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly identifies the resource (cross-venue spread), the two venues, and the comparison basis. The detailed modes ('topic' vs explicit ticker/slug) further distinguish it from generic market tools and sibling Polymarket 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?

The description gives explicit mode-selection guidance: use 'topic' for 10 pre-mapped macro shortcuts, and use explicit 'kalshi_event_ticker' + 'polymarket_event_slug' for custom pairings. It also warns that most pre-mapped topics currently return compatibility warnings, so pre-mapped does not imply tradeable. It does not explicitly contrast against sibling tools like polymarket_arbitrage, but the in-tool usage guidance is clear and practical.

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 provide readOnlyHint, idempotentHint, destructiveHint=true/false. Description adds scoping to identifier and pairing with remember/forget, but no additional safety or mutation details needed 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?

One paragraph, front-loaded with core action. Every sentence provides unique value: retrieval mechanism, listing behavior, use cases, scoping, and sibling tool pairing.

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 a simple tool with one optional parameter and no output schema. Covers behavior, use cases, scoping, and pairing with other tools without 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 covers 100% of parameters with description. Description adds context: 'omit key to list all keys' and explains key purpose as memory key, enhancing understanding beyond 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?

Clearly states the tool retrieves previously saved values via 'remember' or lists all keys if omitted. Specifies verb (retrieve/list) and resource (saved values/keys), and distinguishes from siblings 'remember' and 'forget'.

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

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

Explains when to use: 'to look up context the agent stored earlier' and contrasts with re-deriving from scratch. Mentions scoping and pairing with remember/forget, though no explicit exclusion criteria.

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?

Describes beyond annotations: explains mark_read effect on subsequent calls, return fields (source, citation_uri), and filtering behavior, adding value beyond readOnlyHint and idempotentHint.

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

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

Concise with front-loaded purpose, no filler, each sentence adds essential 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?

Given complete annotations and full schema coverage, the description covers return values, filtering, side effects, and alternative access, leaving no 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?

Adds meaning beyond schema descriptions, e.g., 'set mark_read:true to flag returned events read so the next call only shows newer ones', enhancing understanding of parameter side effects.

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 clearly states the tool 'Pull fired events from your subscription feed' and specifies return fields and filtering options, distinguishing it from siblings like list_subscriptions.

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?

Provides context like 'Polls work fine' and mentions an alternative API endpoint, guiding when to use the tool vs. direct access.

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

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

The description discloses behavioral details beyond annotations: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains fallback logic, and mentions potential issues like rate limiting and API sunset. Annotations confirm read-only and idempotent behavior, with no contradiction.

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

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

The description is fairly long but front-loaded with concrete examples. Every sentence adds value, though some repetition could be trimmed. It is well-structured for an AI agent to grasp quickly.

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 lacking an output schema, the description explains the return format (changes grouped by source, total_changes count, citation URIs). It also covers fallback behavior and soft-failure for USPTO, making it complete for a complex multi-source 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 input schema already has 100% description coverage for all three parameters. The description adds further context, such as accepted formats for `since` (ISO date or relative shorthand) and the fallback behavior for news sources, enhancing understanding 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?

The description clearly states the tool's purpose: providing a change feed for a company in a recent time window. It includes example queries and explicitly distinguishes it from the sibling tool entity_profile, which is for static profiles.

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 provides explicit guidance on when to use this tool (e.g., 'What's new with X') and when not to use it, directing users to entity_profile for static profiles. It also gives example values for the `since` parameter.

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 give idempotentHint=true and destructiveHint=false. The description goes beyond by clarifying scoping (by agent identifier), persistence differences (authenticated vs. anonymous, 24-hour expiry), and that it is a key-value store. No contradictions with 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?

Four sentences, no filler. Front-loaded with the core purpose. Every sentence adds value—scope, use cases, pairing 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?

Given 2 simple parameters and no output schema, the description adequately explains the mechanics (key-value, scoped, persistence) and lifecycle (pairing with recall/forget). No gaps for a tool of this complexity.

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

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

Schema coverage is 100% with good descriptions for key and value. The description adds examples of key names and value types (findings, addresses, etc.) but this is incremental over the schema's own descriptions. Baseline of 3 is appropriate.

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

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

The description starts with a clear verb+resource: 'Save data the agent will need to reuse later'. It includes specific examples (resolved ticker, target address, user preference, research subject) and distinguishes from sibling tools like recall and forget.

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 'Use when you discover something worth carrying forward' and directly names alternatives: 'Pair with recall to retrieve later, forget to delete.' This provides clear when-to-use and when-not-to-use guidance.

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

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

The description goes far beyond the readOnly/idempotent/destructive annotations, explaining graceful degradation, unresolved identifiers being explicitly reported, ambiguous matches returning 'figi_candidates', ISIN-to-LEI mapping, and internal cascading through lookup endpoints. No contradiction with annotations exists.

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

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

The description is long and dense with nested parentheticals, but every sentence adds operational value. It is front-loaded with user-phrase examples and the 'Use FIRST' directive, though a bit more paragraph structure would improve scannability.

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 explaining return behavior, and it does so thoroughly: named fields, unresolved and candidate behavior, ownership data, non-equity instrument coverage, and degradation semantics are all covered. An agent can invoke the tool correctly with just this description.

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 description adds substantial meaning beyond the schema: it explains that the value must be the entity name only, gives a concrete bond-issuer example, clarifies that trailing security-class words fail, and details how different input forms (ticker, CIK, ISIN, brand, generic name) are handled.

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 clearly states the tool resolves user-spoken names into canonical identifiers other tools require, with explicit examples of natural-language prompts. It covers supported types ('company', 'drug') and the exact identifier set returned, making it distinct from siblings like entity_profile.

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 explicitly says 'Use FIRST whenever you have a name but need an ID', which gives strong usage direction. It does not name specific alternative tools or list when not to use it, but the guidance is clear enough for an agent to select it appropriately.

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 indicate read-only and idempotent behavior. The description adds important detail: it probes each entity by calling 'ai_visibility_check', and returns a ranked list with score, confidence, and signal density. No annotation contradictions.

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 sentences with a parenthetical example, front-loading the core purpose. Every sentence provides value with no redundancy 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?

Despite no output schema, the description explains return format (ranked list with metrics). It covers the delegation mechanism, usage context, and parameter roles. For a tool with 4 parameters, this is comprehensive enough for an agent to understand invocation and results.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about the ordering of entities (first is subject) and the ranking behavior, but does not significantly augment parameter meanings beyond what the schema already provides.

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 clearly states the tool compares AI visibility across multiple entities side-by-side, distinguishing it from the sibling 'ai_visibility_check' which handles single entities. It gives a concrete use case and example question, making the purpose unmistakable.

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

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

The description explains it is useful for competitive AI-marketing audits and clarifies that the first entity is treated as the subject. It implicitly suggests using 'ai_visibility_check' for single entities, but lacks explicit when-not-to-use guidance or mention of alternatives like 'compare_entities'.

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 indicate read-only, idempotent, not destructive. Description adds composite external API calls, partial failure behavior, first measurement delay (5-30s), and return structure, providing context 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?

Description is informative and well-structured, starting with purpose, usage, details, then limitations. Though lengthy, each sentence adds value. Slight room for tighter phrasing.

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

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

Given no output schema, description covers returned fields (summary block, advisories, links, alternatives). Includes limitations, usage context, and behavior, making it sufficiently complete for the tool's complexity.

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%. Description adds useful details: scoped packages accepted for 'package', and 'version' defaults to latest. Adds clarity beyond the schema descriptions.

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

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

The description clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. The verb 'scan dependency' is specific and distinct from sibling 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?

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also mentions NPM-only scope and alternative direct deps.dev usage for other ecosystems.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), the description details the embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K), truncation behavior, and offset return. This significantly enriches the agent's understanding of tool 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?

The description is front-loaded with the core concept and proceeds to explain usage, output, and technical details. Every sentence adds value, though it could be slightly tightened (e.g., the pairing note is helpful but not essential). Overall efficient for the information density.

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 no output schema, the description covers return format (passages, offsets, similarity scores), input constraints (200K chars, truncation with flag), and technical details (embeddings, windowing). This is comprehensive for a search tool, leaving little ambiguity about behavior or outputs.

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

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

With 100% schema coverage, the schema already describes parameters. The description adds practical context: 'Pass the text you already pulled' for 'text', examples for 'query', and default/max for 'limit'. This extra context justifies a score above the baseline 3.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article, tool result). It specifies the output (passages with offsets and similarity scores). Although it doesn't explicitly differentiate from every sibling, it mentions pairing with ask_pipeworx_grounded, which provides some contextual distinction.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also advises that passages carry offsets for verification. No explicit when-not-to-use or alternatives, but the guidance is clear and actionable.

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 indicate a mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds behavioral details: requires OAuth, returns subscription id, supports specific types with parameters, delivery channels with limitations (SMS 10/day, webhook auto-disabled after 10 failures), and webhook secret returned once. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the core action and return. It then systematically covers types and delivery channels. Every sentence provides necessary information without redundancy. Length is appropriate for the tool's complexity.

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

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

Given the tool's complexity (multiple subscription types, delivery options, and constraints), the description covers all essential aspects: purpose, return value, prerequisites, type parameters, delivery configurations, and limitations. No output schema exists, but the description explains the return (subscription id and webhook secret).

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 description significantly enriches each parameter with examples and constraints. For 'type', it lists all enum values with explanations. For 'params', it provides type-specific JSON examples. For 'delivery', it details each channel with verification steps and limits. The description adds substantial value 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?

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation. The verb 'Create' and resource 'subscription' are specific.

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 provides guidance on when to use (proactive monitoring) and prerequisites (Pipeworx OAuth account). It also lists supported types and delivery options. However, it does not explicitly state when not to use or compare to alternatives like 'recent_alerts' for pulling.

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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it returns example questions with tool calls, drawn from a live catalog, and that calling with no arguments gives a full spread. No contradictions with annotations.

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

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

The description is well-structured: it starts with alternative phrasings, states the purpose, describes the return value, then gives argument and usage guidance. Every sentence adds value without repetition, earning its length.

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

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

Given the tool's role as an orientation tool and the richness of annotations, the description is complete. It covers what the tool returns, how to call it with arguments, and when to use it. No output schema is needed as the return is example questions.

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% (one optional parameter with description). The description adds meaning by listing the focus areas (finance, pharma, etc.) and explaining the effect of omitting the parameter.

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

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

The description clearly states the tool's purpose: it is the onboarding entry point for a new agent to discover what questions to ask Pipeworx. It returns category-bucketed example questions with tool calls, which distinguishes it from siblings like ask_pipeworx that execute queries.

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 explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear guidance on when to invoke. It also explains argument options: no arguments for full spread or topic to focus, and implies when not to use (if you already know).

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 indicate readOnlyHint=false and destructiveHint=false. The description adds valuable behavioral context: 'The row is deactivated (not deleted) so its historical events stay available,' which goes beyond annotations and clarifies the mutation's effect.

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 three sentences and directly conveys key information. It is concise with no extraneous content, though it could potentially combine the first two sentences without loss of clarity.

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

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

The description covers essential aspects: the effect (deactivation), ownership constraint, and consequence for history. No output schema exists, but for a simple mutation tool, the description provides sufficient completeness.

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%, with the 'id' parameter described as 'Subscription id (uuid) returned by subscribe.' The description does not add additional semantic detail beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by its action.

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 explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use the tool. It does not explicitly list when not to use it or alternatives, but the context is clear.

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

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

Annotations already mark it as read-only/idempotent/non-destructive, but the description goes well beyond by disclosing the exact verdict set, the meaning of could_not_verify (with verification_error payload) as non-evidence, the unsupported state, and the routing to live sources with verbatim evidence and citations. This is rich behavioral context beyond the annotations.

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

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

The description is well-structured: opening with natural-language triggers, followed by usage guidance, routing logic, return values, and important caller caveats. Every sentence adds value, and the length is justified for a tool with nuanced verdict semantics.

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

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

No output schema exists, so the description carries the full burden of explaining return values. It does so comprehensively, listing all verdict values, the error semantics for could_not_verify, the unsupported state, citation format, and the fallback behavior. This is complete enough for an agent to invoke and interpret results correctly.

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

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

Input schema has 100% coverage: both parameters have detailed descriptions with examples and tolerance behavior. The description adds high-level context about percent-delta math but does not add meaning beyond what the schema already provides for each parameter. 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?

The description clearly identifies a specific verb and resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools like deep_research and compare_entities by focusing on fact-check verdicts, and even provides natural-language invocation examples ("Is it true that…" / "fact check").

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: "Use whenever the agent needs to check whether something a user said is factually correct." It also differentiates between company-financial claims (SEC EDGAR + XBRL fast path) and all other claims (grounded pipeline fallback), and notes it replaces 4–6 sequential calls, giving clear guidance on when this tool is the right choice.

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