Geonames

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context: default free model, optional Anthropic with BYO key, and return structure (per-model score/confidence/signals/raw_response + combined view). 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?

Three sentences with zero waste. Front-loaded with main action and key details. Every sentence adds value: purpose, model behavior, use cases.

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, description outlines return fields. For a tool with 4 parameters (1 required), it covers purpose, parameter behavior, use cases, and model selection. No obvious gaps.

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

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

Schema coverage is 100%, so baseline is 3. Description adds beyond schema: explains default model, that '_apiKey' is only needed for Anthropic, and gives concrete examples for 'entity' (e.g., 'Pipeworx', 'OpenInvoice') and 'context' (e.g., 'Boston restaurant').

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 states specific verb 'probe' and resource 'LLMs for visibility score (0-100)'. Clearly distinguishes from sibling tools like 'ask_pipeworx' and 'deep_research' by focusing on multi-model audit rather than general Q&A.

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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but doesn't explicitly exclude alternatives. Could mention when not to use (e.g., when only a single simple answer is needed, prefer 'ask_pipeworx'), 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 readOnly, idempotent, openWorld, and non-destructive hints. The description adds useful behavioral context: it routes dynamically across 5,501 tools, fills arguments automatically, returns stable citation URIs, and is efficient ('one fast call'). 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?

The description is long but effectively front-loaded with the key preference ('PREFER OVER WEB SEARCH'), then covers scope, examples, and escalation paths in logical order. A few redundant phrases ('works on every tier, one fast call') add slight bloat, but the structure is scannable and every section 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?

Even without an output schema, the description fully equips an agent to decide when and how to invoke the tool. It covers the scope of data sources, gives concrete examples, explains the default entry-point status, and clearly delineates escalation to sibling tools. No critical context 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%—all parameters are aliases for 'question', and the schema already describes it as a natural-language question. The description adds example queries and trigger phrases, but does not add parameter-level semantics beyond what the schema provides. 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 defines the tool's function: it routes questions to one of 5,501 tools and returns structured answers with citations. It explicitly differentiates from siblings (ask_pipeworx_grounded, deep_research) and specifies its scope with concrete examples.

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 instructs to prefer this over web search, provides trigger phrases ('what is', 'look up', 'find'), and names alternatives with specific conditions ('use ask_pipeworx_grounded' for hallucination-resistant answers, 'deep_research' for broad/multi-part questions). This gives 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context about the beta nature, current lack of active candidate (matching ask_pipeworx exactly), and that it is a full router with no fallback. This goes beyond annotations without 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 three sentences and reasonably concise, with the key beta context front-loaded. Every sentence contributes value, though 'Falls back to nothing' sentence could be considered slightly repetitive but still useful.

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 (5,501 tools) and lack of output schema, the description adequately conveys the identical response shape, current equivalence to the stable router, and the experimental purpose. It does not detail response formats but points to ask_pipeworx, which is sufficient in 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?

The input schema has 100% coverage with all aliases described. The description adds no additional parameter semantics beyond noting 'same arguments', 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?

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,501 tools and arguments. It distinguishes itself from siblings by emphasizing its experimental routing improvements, making the purpose explicit and differentiated.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions results are compared against the stable router. It provides context but does not explicitly list exclusions like 'use stable for production', though the experimental implication 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the exact return structure, possible refusal reasons, the extra LLM call cost, and the constraint of using only tool result content. This provides rich behavioral context that annotations do not cover.

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 packed with valuable information, but it is logically structured with a clear progression: what it is, how it works, return format, when to use, and cost trade-off. It avoids fluff, though slightly longer than necessary; every sentence earns its place.

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

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

For a complex tool with no output schema, the description explains the full return contract including success and refusal shapes, lists specific refusal reasons, and covers the cost/usage trade-off. It is complete enough for an agent to decide 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?

Schema description coverage is 100% with all parameters being aliases for 'question', which the schema already fully describes. The description adds no new parameter semantics beyond the schema, so the 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 defines the tool as a hallucination-resistant answer mode for high-stakes reads, with specific verbs like 'fetches' and 'EXTRACTS'. It distinguishes itself from sibling ask_pipeworx by focusing on grounded, evidence-based answers with explicit refusal behavior, making its 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?

Explicit usage guidance is provided: use when answers will be quoted, cited, or acted on and the agent must not invent facts, with examples (financial verdicts, legal claims, medical lookups). It also explicitly directs to prefer ask_pipeworx for casual lookups, naming the alternative and the trade-off (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?

The description extensively discloses behavioral traits beyond annotations, including resolution confidence handling, short-circuit on low-confidence matches, closed market detection, wide-spread illiquidity warnings, cancellation rule parsing, and news fallback behavior. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds rich context without 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 very comprehensive but lengthy, with detailed sections on classifiers, fan-out examples, response shapes, resolver contract, safety, and resolution rules. While well-structured, it could be more concise for an agent-facing description; some details could be moved to external documentation. Still, every sentence serves a purpose.

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 (3 parameters, no output schema, numerous behavioral aspects), the description covers all necessary information: input formats, resolution process, fan-out logic, response structure (market, analysis, evidence), safety mechanisms, and cancellation rules. It compensates for the lack of output schema by detailing the return shape comprehensively.

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 all three parameters documented. The description adds value by explaining how depth affects fan-out ('quick = 2-3 evidence sources, thorough = full fan-out') and the trade-off for include_raw (response size vs. detail). This goes beyond the schema, earning a 4.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the exact verb (research), resource (Polymarket bet with Pipeworx data), and scope (one call). The tool is well-distinguished from siblings like polymarket_arbitrage and polymarket_edges, which focus on different aspects.

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 usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly mention when to avoid this tool or what alternatives to use, relying on context from sibling tool names. This is clear but could be more direct.

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, and destructiveHint. The description adds rich behavioral context: data sources (SEC EDGAR/XBRL, FAERS, FDA, clinical trials), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. 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 efficient and front-loaded with key trigger phrases. Bold and structure are well used. Slight redundancy ('side-by-side comparison', 'parallel call') but overall it is appropriately sized and focused.

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, no output schema, and rich annotations, the description provides complete context: data sources, sorting, citation URIs, and even notes on fiscal year handling. An agent can fully understand what to expect and how to interpret results.

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

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

Schema coverage is 100%, but the description adds value by explaining the meaning of each enum (company: financials, drug: adverse events) and giving format examples for values (tickers/CIKs for company, names for drug). This goes beyond the schema's minimal 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?

Description explicitly states the tool does side-by-side comparison of 2-5 companies or drugs, with trigger phrases like 'compare X and Y', 'X vs Y', etc. It clearly distinguishes from siblings like entity_profile (single entity lookups) and positions itself as a replacement for multiple sequential lookups.

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 advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving clear usage context. It also breaks down what data is pulled for each type. Lacks explicit 'when not to use' scenarios (e.g., detailed single-entity profiling), but the context is strong.

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, open-world, idempotent, non-destructive; the description adds a wealth of context: account requirements, paid depth tier, parallel tool routing, return packet structure (verbatim evidence, confidence, source, fetched_at, citations), gaps[] for unanswered facets, contradiction detection for standard/thorough, hop mechanics, semantic excerpting, and timing expectations. 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?

The description is a single dense ~250-word block with heavy use of dashes and semicolons. While every detail is useful, the lack of paragraph breaks or bulleted structure makes it harder to parse quickly. It is thorough but not concise; structuring into short labeled sections would earn a higher 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 and absence of an output schema, the description fully covers what the agent needs: return format (findings packet, citations, gaps[], contradictions[], hop field), edge cases (gaps for non-catalog topics), auth prerequisites, latency expectations, and when to select a different sibling. No significant gaps remain.

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

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

Input schema coverage is 100%, so baseline is 3. The description adds only minor extra context: thorough requires a paid plan, and question can be broad/multi-part (though the schema already states this). It mostly echoes the schema's depth enum details rather than adding new meaning, so the value is marginal.

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+resource: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources' and clarifies it is 'NOT open-web search.' It distinguishes from siblings by explicitly naming ask_pipeworx as the alternative for single lookups and news, making the tool's unique batch/faceted structured-research role clear.

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

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

Provides explicit when/when-not guidance: 'Best for broad/multi-part questions over structured data,' 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx,' and 'If you are not signed in, use ask_pipeworx instead.' It names alternatives and gives behavioral cues (empty gaps[] for news topics), leaving no ambiguity about when this tool is appropriate.

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 key behavior: returns top-N relevant tools with full schemas and examples, ready to call directly. 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?

Somewhat long but every sentence adds value. Front-loads core purpose and usage. Could be slightly tighter, but well-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?

Given no output schema, the description fully explains what is returned (names, descriptions, schemas with examples) and that results are ready to call. No gaps for this 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%, so baseline is 3. Description adds aliases explanation and default/max for limit, but that is also in schema. No significant new semantic info beyond what schema 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 it finds tools by describing the data or task, lists numerous specific domains, and distinguishes itself from siblings as the discovery tool. The verb 'Find' and resource 'tools' 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?

Explicitly says 'Use when you need to browse, search, look up, or discover' and 'Call this FIRST when you have many tools available'. Lacks explicit when-not-to-use or alternatives, 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the fan-out across multiple sources, specifics of returned data (e.g., up to 5 filings, latest fundamentals), fallback behavior (GDELT→GNews), and a sunset note for patents. This adds significant behavioral context.

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 example queries and a clear statement of purpose. It is dense but slightly longer than necessary; however, every sentence serves a purpose. It is 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?

Given the tool's complexity (multiple data sources, fallbacks, limitations), the description covers all key aspects: input types, output fields, data sourcing, caveats (patents sunset, news fallback), and output structure. No output schema exists, but description sufficiently explains return values.

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 clear descriptions for both parameters. The description reiterates the input constraints (ticker/CIK, no names) but does not add new semantic detail beyond what the schema already provides. 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 states the tool's purpose: a full cross-source profile of a US public company in one parallel call. It provides example user queries and explicitly distinguishes it from chaining single-purpose lookups, aligning with sibling differentiation.

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 prefer this tool over chaining single-pack lookups when a holistic view is needed. It also provides specific guidance on supported inputs (ticker or CIK) and directs users to resolve_entity for names, covering when to use and when not to.

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 non-destructive behavior. The description adds value by listing the return fields (place name, country, admin region, postal code, coordinates) and explaining the two query modes, surpassing the annotation baseline.

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 crisp sentences: first states purpose, second elaborates with examples and return fields. No wasted words, front-loaded, 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?

For a tool with 5 parameters (1 required) and no output schema, the description covers both usage modes, return fields, and the importance of country. It is complete enough for an agent to invoke correctly.

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

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

Schema description coverage is 100%. The description adds meaning beyond schema by explaining the two mutually exclusive usage modes (postal_code or place), which helps the agent choose parameters correctly.

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: looking up postal/ZIP codes and places by each other, with concrete examples. It distinguishes itself from siblings like search_geonames by focusing on reverse lookups.

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 clear usage instructions: use 'postal_code' with country to find places, or 'place' with country to find codes. It emphasizes the importance of country but does not explicitly mention alternatives or when not to use the 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 destructive and idempotent behavior. Description confirms deletion but does not explicitly state idempotency or provide additional behavioral context beyond what annotations provide.

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

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

Two sentences containing only essential information, front-loaded with purpose.

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?

Adequate for a simple tool with one parameter and no output schema. Missing explicit mention of idempotent behavior (deleting a non-existent key is safe) despite annotation.

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

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

Schema coverage is 100% and property description 'Memory key to delete' is clear. Description adds no extra parameter 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?

Clearly states 'Delete a previously stored memory by key' with a specific verb and resource. Distinguishes from siblings '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 says when to use: context stale, task done, or clearing sensitive data. Also mentions pairing with sibling tools.

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

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

Annotations already indicate safe, idempotent read. Description adds how it works (fetches page, extracts title/description/key links, outputs markdown) and output location hint. 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?

Four sentences: purpose, process, output, use cases. Nothing redundant, front-loaded with key action.

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?

Simple tool with two parameters, no output schema. Description covers what it does, output format, and use cases. Minor missing details (e.g., error handling) are acceptable for 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%, so description adds no new parameter info. 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 uses specific verb 'generate' and resource 'llms.txt file', clearly stating it produces a standard markdown file for AI crawlers. It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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 lists three use cases (client site indexing, own project drafting, competitor auditing). Does not mention when to avoid using or compare with siblings, but context is clear and helpful.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that results are sorted by distance, which is behavioral context beyond what annotations provide. 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 extremely concise with two sentences and an example that front-loads the action. Every sentence adds value without unnecessary detail.

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, full schema coverage, presence of annotations, and existence of an output schema, the description provides sufficient context. It explains the tool's function, return type, and ordering, leaving no gap for the agent to misinterpret.

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 has 100% description coverage, so the baseline is 3. The description's example shows usage but does not add semantic meaning beyond what the schema already provides for each 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 finds places near a given latitude/longitude, specifying return types (cities, landmarks, features) and ordering (by distance). The example with Paris coordinates concretely illustrates the purpose. This is specific and unambiguous.

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

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

No explicit guidance on when to use this tool versus alternative sibling tools like search_geonames or search_within. The description implies usage through the example but does not provide context for when not to use it or mention any prerequisites.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value by listing the exact return fields (timezone ID, offsets, local time, sunrise, sunset) and an example, providing richer behavioral context beyond the structured 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 two sentences: the first states purpose and returns, the second provides an example. No wasted words, front-loaded with key 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 the tool's simplicity (3 parameters, no nested objects), the description fully covers what the tool does, what it returns, and how to use it via example. Annotations and output schema (implied) further support 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 each parameter having a description. The description adds an example call but does not significantly enhance parameter meaning beyond the schema. 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?

Description clearly states 'Get timezone information for a latitude/longitude location,' which is specific and distinct from sibling tools like search_geonames. It provides a precise verb-resource combination.

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 when to use this tool (for timezone info given lat/lng). It does not provide explicit when-not-to-use or alternative tools, but the context is clear enough to avoid misuse.

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

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

Annotations already declare read-only, idempotent, non-destructive. The description adds return field details but no additional behavioral traits 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?

Two sentences, front-loaded with purpose and return fields, then usage guidance. 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?

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage. Complete given the low 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 covers the single parameter with a description (100% coverage). The tool description adds no additional meaning beyond what the schema 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 it lists the caller's active subscriptions and specifies return fields. However, it does not explicitly differentiate from sibling tools like 'subscribe' or 'unsubscribe', though the purpose is clear.

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

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

Provides explicit usage guidance: use to review subscriptions before adding more or to get an id for cancellation. This helps the agent decide when to invoke.

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 follow-up behavior (claim_token for checking resolution status), rate limits (5 per identifier per day), roadmap impact, and the fact that it's free. These details go well beyond the sparse annotations (all false hints) and there is 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 concise despite its length: each sentence carries unique information, structured logically from purpose to usage to exclusions to follow-up. It front-loads the core purpose and avoids 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 tool with 4 parameters, nested objects, no output schema, and sparse annotations, the description is remarkably complete. It covers purpose, usage boundaries, parameter behavior, token lifecycle, and operational constraints, leaving no meaningful questions unanswered.

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 the schema has 100% parameter descriptions, the tool description enriches semantics: it explains how claim_token is used ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), instructs users to describe issues in terms of Pipeworx tools, and clarifies the context object's purpose—adding value beyond the raw 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 opens with a specific action—'Tell the Pipeworx team something is broken, missing, or needs to exist'—and clearly enumerates the feedback types (bug, feature/data_gap, praise). It names the resource (Pipeworx tools) and differentiates from sibling research tools by being the only feedback channel.

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

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

Explicit when-to-use guidance is given: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes an exclusion criterion—'ONLY for tools served by this Pipeworx connection'—and directs users to file with the correct server otherwise.

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?

Description adds value beyond annotations: explains data source (CF analytics-engine), no PII, caching behavior (5min-1h). Annotations already declare readOnly, idempotent, non-destructive.

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

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

Three sentences with bulleted use cases, no filler. Front-loaded with return type and window options.

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 one optional parameter, no output schema, and strong annotations, the description covers return structure, data source, privacy, and caching adequately.

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 well-described enum parameter. Description adds practical guidance: shorter windows for hot trends, longer for steady-state demand.

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 it returns top tools, top packs, and total call volume over a specified window. Distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on trending data rather than answering questions.

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 three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case). Does not include explicit when-not-to-use, but context is clear enough.

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?

Description discloses extensive behavioral details beyond annotations, including algorithms (monotonicity, partition-sum), semantic anchor threshold (Jaccard ≥0.30), partition filter (placeholder slugs >20% nullify), and fill check logic. Aligns with readOnlyHint and non-destructive 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?

While dense, every sentence serves a purpose and the description is front-loaded with the primary action. Some redundancy could be trimmed, but the complexity justifies the length. Structured logically from overview to modes to details.

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 complex arbitrage tool with no output schema, the description thoroughly explains response fields, fill check mechanics, and limitations. References sibling tools for complementary functionality. Covers all necessary guidance for correct invocation and interpretation.

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, and the description adds significant value by explaining behavior, giving concrete examples, and detailing algorithm implications. Slightly above baseline due to rich extra 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?

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two distinct modes (event and topic) and differentiates from sibling tools like polymarket_edges and 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?

Explicitly explains when to call with no args (trending scan), pass `event` for specific market, or `topic` for cross-event scanning. Provides recommendations, examples, and conditions to avoid (e.g., fill check warning not to trade if realizable_edge_pp ≤ 0). References sibling tool for custom sizing.

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 extensively discloses behavioral traits beyond annotations: it details model families (crypto_price, news_momentum, structural_arbitrage), edge calculation (edge_pp_net after slippage), Kelly sizing caps (0.25), 24h move warning, caching at KV level keyed on all knobs, and diagnostics for empty segments. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all true/false appropriately).

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 lengthy but compact with information. It front-loads the purpose and then systematically covers segments, edge fields, knobs, and response structure. Every sentence adds value, though the wall of text could be better organized with bullet points or sections for improved scanning by an AI agent.

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 9 parameters, no output schema, and rich annotations, the description is remarkably complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), caching behavior (1h at KV level), and even provides context on limitations (Fed bets unreliable without paid data). No obvious gaps for an agent to invoke the tool confidently.

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

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

Schema coverage is 100% (baseline 3). The description adds significant meaning beyond schema: it explains the purpose of each knob (e.g., 'min_liquidity' description explains dropping thin-book opportunities), provides examples (e.g., 'Set to 2 to require tight books'), and clarifies interactions (e.g., 'min_partition_leg_kelly' applies to per-leg Kelly inside partitions). This adds substantial value beyond parameter names and 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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses a specific verb (scan) and resource (Polymarket markets), and distinguishes itself from siblings like polymarket_arbitrage by focusing on disagreement with Pipeworx data rather than pure arbitrage or 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?

The description provides explicit context for when to use the tool ('what should I bet on today') and explains the various filters and knobs. However, it does not explicitly state when not to use this tool versus alternatives like polymarket_arbitrage, though the detailed breakdown of segments and model families implies distinctions.

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 as true, and destructiveHint false. The description adds substantial behavioral context: it reads from daily snapshots with a 60-day TTL, decay numbers from daily closes, snapshot gaps on cache misses, and explains the response structure including tracked, expired, and snapshot_dates arrays with their fields. 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 detailed and well-organized, starting with the purpose then explaining the response structure with labeled arrays. However, it is somewhat verbose and includes information that could be more terse, such as the full breakdown of tracked arrays and their sub-fields. Still, it remains clear.

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 complexity of the tool (time-series decay analysis) and no output schema, the description fully explains the return format: tracked, expired, snapshot_dates arrays with their fields, and limitations (TTL, gaps). This provides sufficient context for an agent to understand and use the tool.

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

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

Schema coverage is 100% with descriptions for both parameters (days, window). The description adds meaning beyond schema: explains defaults (14 for days, '1wk' for window), constraints (max 30 for days), and the concept of snapshot families ('window family'). This enriches parameter 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's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots. Answers 'how long has this edge existed and is it shrinking?'' It uses specific verbs and resources, and distinguishes from siblings like polymarket_edges by focusing on historical trends rather than current 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?

The description provides clear context for when to use the tool: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' It also gives default and max values for the days parameter. However, it does not explicitly mention when not to use or list alternatives, though sibling tools are available.

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 (all safe). The description adds rich behavioral context: walks the order book ladder, returns verdicts (clean|degraded|cannot_fill), warns about thin books and forced directional risk. This goes beyond annotations to explain exactly what the tool does internally and what risks it mitigates.

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: starts with purpose, then uses clear section headers for SINGLE-MARKET and BASKET modes. Every sentence adds value (no filler). However, it could be slightly more concise without losing clarity, hence a 4 instead of 5.

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

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

Despite lacking an output schema, the description fully documents all return values for both modes (top_of_book, verdict for single-market; theoretical_sum, capture_ratio, thin_legs for basket). It explains edge cases (thin books, partial fills) and the dominant loss mode. Combined with high schema coverage and annotations, the description is 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%, and the description adds significant meaning beyond schema field descriptions. For example, it explains that `size_usd` for basket is 'settlement notional — shares per leg, each paying $1 at resolution,' and describes default behavior for `side` in basket mode (auto-detect based on partition sum). Each parameter's role in both modes is clearly elaborated.

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 it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes with precise verb-resource combinations. Additionally, it explicitly ties usage to sibling tools by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' making its purpose unambiguous and distinct.

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 when-to-use guidance: before acting on arbitrage signals or edge trades above ~$500. It also explains when-not-to-use by warning about partial basket fills converting arb into unhedged directional positions. Requirements are clear (one of `market` or `event`), and the two modes are thoroughly explained with usage 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 mark the tool as read-only, open-world, and idempotent. The description adds extensive behavioral context: compatibility_warning scenarios, temporal_alignment, skipped_cross_type/subtype counters, and the caveat that real spreads are rarer than shortcuts suggest. This goes well beyond annotations.

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

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

The description is long but well-structured: it starts with purpose, then modes, response, and safety fields. Every sentence adds value. Minor redundancy (e.g., 'pre-mapped' repeated) but acceptable for the complexity.

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

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

With no output schema, the description fully describes the response structure: leg-by-leg prices, matched spreads, and safety fields. It covers all necessary aspects for an agent to understand inputs, outputs, and caveats.

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 adds valuable context: it lists the exact pre-mapped topics, explains that explicit tickers override topics, and provides examples. This meaningfully extends 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb ('spread') and resource ('cross-venue'), and includes enough detail to distinguish it from sibling tools like 'polymarket_arbitrage' or '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?

The description explains when to use (comparing pricing across venues) and includes compatibility_warning fields that indicate when the tool should not be relied upon (non-equivalent bet shapes or unrelated events). It also notes that pre-mapped topics often return warnings. However, it does not explicitly mention alternative tools among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to reiterate safety. It adds value by disclosing scoping ('Scoped to your identifier') and pairing with remember/forget. It does not describe return format or performance, but given the simplicity and annotation coverage, this is sufficient.

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

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

Three sentences, each with clear purpose. First sentence states the core action. Second explains when to use. Third adds important context about scoping and pairing. No redundant or vague language. Perfectly front-loaded.

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

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

With no output schema, the description should explain what the tool returns (e.g., value format, list of keys). It only says 'retrieve a value' and 'list all saved keys' but does not specify the data structure or type. However, given the tool's simplicity and symmetry with remember, this is a mild omission. It is adequate but not fully complete.

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

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

Schema description coverage is 100% and the schema already explains the key parameter and omission behavior. The tool description reinforces this with additional context about listing all keys and the use case. It adds marginal value but is consistent and clear.

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 verb 'Retrieve' and resource 'value previously saved via remember' or 'list all saved keys'. It distinguishes from siblings by naming remember and forget, and explains when to use each mode (omit key for listing). The use case is concrete: look up stored context like ticker or address.

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 explicitly states to use this tool to retrieve previously stored context without re-deriving. It implies when not to use (when you want to save, use remember; to delete, use forget). However, it could be more explicit about situations where recall is inappropriate (e.g., stale data). Nonetheless, 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?

Adds significant context beyond annotations: explains mark_read side effects (flags events as read), return data structure, and polling suitability. No contradictions with readOnlyHint, idempotentHint, etc.

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

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

Single paragraph, front-loaded with purpose, every sentence contributes. Efficient and well-structured with 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?

Covers purpose, return contents, filtering, side effects, polling, and an alternative method. Without an output schema, it adequately describes what is returned. Annotations cover safety, so 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?

Schema descriptions cover all 5 parameters, baseline 3. Description adds value with an example filter type (sec_8k) and clarifies mark_read behavior, improving usability beyond schema alone.

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

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

Description clearly states the tool pulls fired events from a subscription feed, lists what each alert carries, and mentions filtering. It distinguishes itself from sibling tools like list_subscriptions by focusing on events rather than 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?

Describes when to use (pull alerts, poll) and provides an alternative endpoint for scripts/dashboards. However, it does not explicitly compare to other sibling tools or state 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds details on source fan-out, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (changes[], total_changes, citation URIs). 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 a single, dense paragraph that front-loads example queries, then explains function, sources, parameter hints, return format, and sibling differentiation. Every sentence is necessary and adds value without 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?

Given the tool's complexity (multiple sources, fallback, soft-fail, structured return), the description covers all aspects: purpose, sources, parameters, return format, and alternative tool. No output schema exists, but return structure is described. Idempotent, read-only behavior is clear from annotations.

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

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

Schema coverage is 100%, so parameters are already described. The tool description adds extra value by providing recommended usage for 'since' (e.g., 'Use 30d or 1m for typical monitoring') and examples for 'value' (ticker or CIK). Only minor improvement possible.

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 provides a change feed for a company by aggregating multiple sources (SEC EDGAR, GDELT/GNews, USPTO). It gives concrete example queries and explicitly distinguishes from the sibling tool entity_profile, which provides 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?

It provides explicit usage examples (e.g., 'What's new with X', 'latest on Y') and directly contrasts with entity_profile, stating when to use that alternative. This gives clear guidance on when to select 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?

Discloses beyond annotations: key-value scoped by identifier, persistent for auth users, 24-hour for anonymous. Annotations provide idempotentHint and destructiveHint, description adds context.

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 concise sentences. Front-loaded with purpose. No redundancy or fluff.

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 tool with two string params and no output schema, description covers all essential: usage context, pairing, scoping, persistence. 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?

Schema has 100% coverage with descriptions for key and value. Description adds examples but doesn't introduce new semantic constraints 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 verb 'Save data' and resource 'key-value pair'. Specifies scope: across conversation or sessions. Examples (ticker, address, preference) distinguish from siblings 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 says when to use: when discovering something worth carrying forward. Lists pairs with recall and forget, and mentions scoping by identifier and persistence duration.

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 substantial context beyond annotations: it details return values (ticker, CIK, company_name, RxCUI, ingredient, brand), citation URIs, input auto-disambiguation, and internal cascading lookups. This complements the readOnly, idempotent, openWorld annotations without 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 well-structured with introductory purpose, supported types, and examples, but it is somewhat long and could be tightened. Every sentence carries value, and important information is front-loaded.

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 return values, supported entity types, input formats, and even the internal cascading behavior. It provides enough context for an agent to invoke the tool correctly without additional documentation.

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 enriches parameter meaning by clarifying accepted inputs (ticker, CIK, name; brand/generic), auto-disambiguation, and expected outputs for each type. This goes beyond the schema's basic enum and value 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 resolves a user-spoken name to the canonical/official identifier, with specific examples of queries. It distinguishes itself from siblings by emphasizing it provides identifiers that other tools require as input, and it explicitly lists supported entity types.

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 provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and concrete query examples. However, it does not mention when not to use the tool or name alternative sibling tools, so it lacks exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds details: it probes each entity, returns ranked list with score, confidence, signal density. No contradiction; adds behavioral 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 two sentences plus a short third; each sentence serves a purpose (main function, process, utility). Front-loaded with the core action. No extraneous 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?

Missing output schema is compensated by description stating return fields. Parameters are fully described. Could mention potential limitations like rate limiting, but overall complete for the task.

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. Description adds value by noting first entity is treated as subject and context disambiguates common names, which goes 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 compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It distinguishes from sibling ai_visibility_check by specifying it is a batch comparison, and uses of ai_visibility_check internally.

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 case ('competitive AI-marketing audits') and an example question. Implicitly contrasts with ai_visibility_check for single entities, but does not fully enumerate when not to use or compare with other siblings 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?

Adds behavioral context beyond annotations: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts while rest still returns. Annotations already indicate read-only, idempotent, non-destructive, so description adds specific failure details.

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?

Single dense paragraph with core purpose front-loaded and details following. Every sentence adds value, though the structure could be slightly more organized with bullet points. Still efficient and focused.

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

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

Covers inputs, outputs, edge cases (partial failures, timeouts), ecosystem scope, and alternatives. Since no output schema exists, description compensates by detailing return format (summary block, advisories, links, versions). Complete for a composite tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds that scoped packages like '@types/node' are accepted for the 'package' parameter, but otherwise no significant enhancement beyond the schema's definitions. Meets but does not exceed baseline.

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

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

Description specifies a composite check for npm packages including license, advisories, version history, bundle size, and more. It clearly states the verb 'check' and resource 'npm package', and distinguishes from siblings by noting NPM-only scope and alternative tools for other ecosystems.

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: 'is X safe / popular / small' or 'what does adding lodash cost me'. Also clarifies NPM-only in v1 and directs other ecosystems to deps.dev:version, providing clear when-not-to-use guidance.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds context about the admin_region field and worldwide coverage. It does not contradict annotations and provides useful behavioral details.

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 primary purpose, includes clear examples, and ends with a sibling reference. Every sentence adds value, and the structure is logical.

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 complexity of the tool (search with multiple parameters and output schema), the description is comprehensive. It details the admin_region field, gives examples for various countries, and mentions output fields. It also references a sibling tool for nearby searches.

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 4 parameters. The description adds examples and explains the admin_region field's meaning, providing additional context 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 explicitly states it searches for places by name and returns administrative divisions, country, coordinates, population, and feature type. It provides specific examples and distinguishes from the sibling tool get_nearby.

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 clear usage context with examples for different countries and explicitly mentions when to use get_nearby as an alternative. It gives concrete instructions on how to use the 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?

Adds specific technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. Annotations already indicate idempotent and non-destructive, and description aligns without 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?

Description is focused and front-loaded with core functionality. Every sentence adds information, though it could be slightly more terse 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?

Despite no output schema, description fully explains return values (passages with offsets and scores). Includes pairing advice with ask_pipeworx_grounded and truncation behavior, making it self-sufficient for an agent.

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 3 parameters (100% coverage). Description adds value by explaining the nature of 'query' with natural-language examples and indicating 'limit' controls top-N passages, plus the result format (offsets, scores). Slightly above baseline due to useful examples.

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 'Semantic search INSIDE a fetched record' with examples (SEC 10-K, article). Distinguishes from siblings by specifying it operates on provided text, but does not explicitly contrast with similar tools like search_geonames.

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 using when the record is too large to include directly, saving context. Mentions pairing with ask_pipeworx_grounded for grounding over passages, but does not explicitly list conditions 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?

Annotations already indicate idempotent and non-destructive. Description adds key behaviors: account requirement, type-specific filtering, SMS cap, webhook signing secret one-time return, and auto-disable after 10 failures. 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?

Tightly packed with information, front-loaded with main action and requirements. Slightly long but every sentence adds value; minor structural improvement possible.

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

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

Covers purpose, parameters, behavior, constraints, and delivery channels. No output schema but returns subscription id as stated. Could mention failure handling or quota details.

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

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

100% schema coverage augmented by detailed examples and usage constraints. Adds rich meaning to each parameter (e.g., enum items, nested object structures) 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 creates a proactive monitoring subscription, lists supported event stream types with examples, and distinguishes from siblings like 'unsubscribe' and '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 explicit context: requires Pipeworx OAuth account, mentions feed vs email/SMS/webhook delivery, and suggests pulling via 'recent_alerts' as alternative. Lacks explicit when-not-to-use vs all siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it returns 'category-bucketed example questions' and uses the 'live catalog', which are useful behavioral details 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 detailed but well-structured: it starts with common questions, then explains behavior, and ends with a usage recommendation. While slightly long, it avoids redundancy and is front-loaded with purpose.

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, the description adequately explains the return format (categories, example questions, tool shapes) and the parameter behavior. It also provides context about usage order relative to sibling tools, making it fully informative for an agent.

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 describes the optional 'topic' parameter with a list of values (e.g., finance, pharma). The description adds context that omitting returns a full spread and that the values focus the results, which enhances 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 this is the onboarding entry point for new agents, answering queries like 'What can I ask?' and explicitly distinguishes it from sibling tools by explaining its role as a discovery tool.

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

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

It explicitly recommends using this tool 'FIRST when you do not yet know what Pipeworx can do' and mentions learning to call meta-tools, but could more explicitly state when not to use it (e.g., if you already know what to ask).

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 behavioral details beyond annotations: it states the row is deactivated (not deleted) and historical events remain available. This aligns with destructiveHint=false and idempotentHint=true, and adds ownership enforcement (not in 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 concise: two sentences efficiently convey the action, ownership constraint, and deactivation behavior. No unnecessary 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 simple tool (one parameter, no output schema), the description covers the action, constraint, and effect adequately. It fully explains what the tool does and its impact.

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 mentions the id parameter but adds limited semantics beyond the schema. With 100% schema coverage, the baseline is 3. No additional details on format or origin are provided.

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 action ('Cancel a subscription by id') and specifies the resource (subscription). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 clear context for when to use the tool: to cancel a subscription by id. It also includes ownership enforcement ('you can only cancel your own subscriptions'), which implicitly guides against using for others' subscriptions. No explicit alternatives are mentioned, but the sibling list provides 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 provide readOnly, openWorld, idempotent, non-destructive hints. The description adds significant detail: fast path for SEC EDGAR + XBRL with exact percent-delta math, grounded pipeline for other claims, and the returned verdict types with evidence and reasoning. 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 informative but verbose, packing many technical details into a single paragraph. It could be more concise and structured for quicker scanning, though it front-loads use-case examples.

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 (two simple params, no output schema), the description fully covers what it does, how it routes claims, what it returns (verdict, value, citation, reasoning), and internal logic. 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?

Schema coverage is 100%; both parameters are described. The description adds value by explaining tolerance_pct default behavior (implied by wording, capped at 5) and suggesting use for hallucination detection, plus providing examples for the claim 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: natural-language claim verification against authoritative sources. It provides multiple verb phrases (e.g., 'fact check', 'verify the claim'), specifies handling of company-financial vs other claims, and distinguishes itself by noting it replaces 4-6 sequential calls, making it specific and unambiguous.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims and other factual claims, but does not provide when-not-to-use or list alternatives among siblings.

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