Mychem

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating safe, non-destructive probing. The description adds value by explaining the default free model (Workers AI Llama) and the BYO key requirement for Anthropic, plus the return structure.

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 pack the action, key nuance (default model and BYO key), and use cases. Front-loaded with the verb 'probe'. Every sentence earns its place 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?

With 4 parameters and no output schema, the description provides the essential return shape (per-model fields + combined view) and usage context. It lacks detail on potential limits or error handling but is adequate 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 coverage is 100%, so each parameter is described. The description adds helpful context beyond the schema: default model, the role of '_apiKey' as BYO, and how 'context' disambiguates. This improves usability for an agent.

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 ('probe one or more LLMs') and the resource ('what they know about a business / brand / product / topic') with a specific output (score 0-100). It distinguishes from siblings like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on visibility scoring across models.

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 concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') giving clear context. It does not explicitly state when not to use or name alternatives, but the context is sufficient for an agent to decide.

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:false. The description adds behavioral context beyond that: it routes, fills arguments, returns structured answers with stable citation URIs, and claims 'one fast call' and 'works on every tier'. It does not contradict annotations.

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

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

The description is long but well-structured: it front-loads the key directive, then gives scope, examples, and alternative routing. Every sentence adds useful guidance for a central default tool. Slight verbosity but justified given the tool's breadth.

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 that routes to thousands of sources, the description covers when to use, what it returns (structured answers with citations), examples, and alternatives. No output schema exists, but the description sufficiently conveys the return type. Nothing critical is missing.

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

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

Schema description coverage is 100% for the single required parameter (question) plus five aliases. The description provides example questions but no additional semantic detail about parameter formatting or constraints beyond what the schema already states. Baseline 3 applies given full schema coverage.

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 (route, return) and resource (5,801 tools across verified sources), with concrete examples of questions. It explicitly contrasts with sibling tools like ask_pipeworx_grounded and deep_research, making its unique role unmistakable.

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

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

It opens with 'PREFER OVER WEB SEARCH', declares itself the default entry point, and gives explicit conditions for when to step up to alternatives (grounded for verbatim evidence, deep_research for broad multi-part questions). Also notes breaking-news coverage. This is textbook usage routing.

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

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

The description discloses that no candidate is active right now so it matches ask_pipeworx exactly, that candidate routing improvements are enabled live whenever under test, and that it does not fall back to anything else. Combined with the read-only annotations, this gives a good sense of expected behavior.

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

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

The description is somewhat repetitive, repeating 'identical', 'same ask_pipeworx', and 'experimental' themes across several sentences. It could be tightened without losing key information, but it is not excessively long.

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

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

The description covers the beta relationship to ask_pipeworx, current active candidate status, routing behavior, and the fact that it is a full working router. It gives enough context for an agent to decide whether to invoke it, though it could mention stable-vs-beta tradeoffs more explicitly.

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

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

The schema already documents all parameters fully as aliases for 'question', and the description adds no additional parameter semantics beyond saying 'same arguments' as ask_pipeworx. Since schema coverage is 100%, 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,801 tools and same arguments. It distinguishes itself from the stable sibling by focusing on 'newest routing' and candidate routing improvements, though it relies on the user knowing what ask_pipeworx does.

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 says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This gives direct selection guidance, though it could more explicitly state when to prefer the stable ask_pipeworx instead.

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

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

Goes beyond annotations by disclosing it extracts only from tool results, returns verbatim evidence, explicit refusal reasons, and costs one extra LLM call. No contradiction with readOnlyHint, openWorldHint, idempotentHint, or destructiveHint.

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

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

The description is thorough but slightly long, front-loading the main purpose and then detailing behavior, usage, and cost. Every sentence adds value, though the return type spec could be trimmed slightly. 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?

Provides complete context: return shape, refusal reasons, use cases, cost trade-off, and differentiation from ask_pipeworx. Since no output schema exists, the description fulfills that role. Nothing essential is missing for correct invocation.

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

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

Schema covers 100% of parameters, including descriptions for all aliases. The description adds no additional parameter-level meaning beyond confirming natural language input, which is already in the schema. Baseline 3 is appropriate given high schema coverage.

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 it is a hallucination-resistant answer mode that extracts answers only from tool results, explicitly distinguishing itself from sibling ask_pipeworx by the extraction step. Specific use case (high-stakes reads) and contrast with casual lookups make 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?

Explicitly states when to use (quoted, cited, or acted on; must not invent facts) and when not (casual lookups, prefer ask_pipeworx). Names the alternative and gives a cost-based reason (one extra LLM call), leaving no ambiguity about selection.

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 behavior. The description adds extensive behavioral detail: fan-out logic, response shapes, resolver contract, parent event extraction, news fallback handling, safety checks (low-confidence, closed markets, wide spreads), and resolution-rule risk. This far exceeds the annotation coverage.

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, starting with core purpose, then detailing behavior, examples, safety notes, and edge cases. It is front-loaded and every section adds necessary context. Some repetition could be trimmed, but the length is justified by the tool's complexity.

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

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

Given the tool's complexity (3 parameters, no output schema, rich behavior), the description is comprehensive. It covers inputs, processing logic, output structure (market, analysis, evidence), edge cases (low confidence, closed markets, wide spreads), and safety warnings. Without an output schema, the description fully explains return values and behavior.

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 further meaning: explaining the 'market' parameter accepts slug, URL, or question text; clarifying the 'depth' enum with defaults; and describing 'include_raw' with practical usage advice. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies the verb 'research' and the resource 'Polymarket bet', and provides explicit use cases ('should I bet on X', 'what does the data say about Y'). Although it does not directly contrast with siblings, the detailed scope and examples effectively distinguish it.

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 scenarios for use (e.g., 'should I bet on X'), includes examples, and lists classifiers and fan-out patterns. It does not explicitly state when not to use the tool or suggest alternatives, but the guidance is clear and context-rich.

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

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

Annotations already cover safety and read-only nature. Description adds value by disclosing returned data sources (ChEMBL, DrugBank, etc.) and content types (mechanism, indication, pharmacology). 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?

Two sentences, front-loaded with purpose, no filler. Every sentence provides essential information.

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

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

Description explains return content well, including sources and data types. For a simple tool with no output schema, this suffices. Could be improved by mentioning response structure or limits.

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 both parameters with descriptions (100% coverage). Description adds examples of valid ids (InChIKey, DrugBank, ChEMBL) but largely restates schema info. Minimal additional semantic value.

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 fetches full aggregated annotations for a single chemical/drug by id, specifying accepted id types and data sources. Distinguished from siblings like entity_profile by focus on chemical annotations.

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?

Implies usage when you have a chemical/drug id and want aggregated annotations, but does not explicitly mention when not to use or compare to sibling tools. No guidance on alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, and result sorting by primary metric. This adds rich behavioral context without contradicting 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 well-structured paragraph of ~100 words, front-loaded with natural language triggers. Every sentence adds value, with 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?

Given the low complexity, 2 required parameters, and rich annotations, the description covers all necessary aspects: data sources, behavior for each type, sorting, and citation URIs. It is fully complete 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 has 2 parameters with 100% coverage, but description adds significant meaning: for type='company' it specifies exact financial metrics (revenue, net income, cash, long-term debt), and for type='drug' it specifies FAERS counts, FDA approvals, trial counts. It also explains result sorting, which the schema does not convey.

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

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

The description starts with natural language triggers ('Compare X and Y', 'X vs Y') and clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It explicitly distinguishes from sequential lookups and provides a verb+resource+scope that effectively differentiates from sibling tools.

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

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

The description explicitly says to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It also explains that type='company' pulls financial data and type='drug' pulls adverse-event data. While it doesn't specify when not to use, the preference statement is strong 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?

Annotations already mark it readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: account requirements, paid tier for 'thorough', expected latency (15-90s), never-invented gaps[], fetchable citations, semantic excerpting, hop fields, and contradictions[]. No statement contradicts 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?

Long but every sentence earns its place; the most important operational constraints (account needed, paid depth, alternative tool) are front-loaded. Dense semicolon-separated details avoid fluff while covering mechanisms, outputs, failure modes, and performance. Formatting with bolded key terms aids scanning.

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

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

Despite no output schema, the description fully characterizes the return value (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field) and the failure behavior (empty gaps[], long duration). For a complex research tool, this is complete enough for an agent to invoke and interpret results without guessing.

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 'question' and 'depth' have descriptions), and the description adds meaning beyond the schema: it defines what each depth value does in terms of hops, gap recovery, contradiction scans, and paid access. The parameter descriptions plus prose give an agent everything needed to pick correct values.

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

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

The description names a specific verb and resource ('grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources in ONE call'), explains the mechanism (decomposition, parallel routing across 5,801 tools), and clearly distinguishes it from ask_pipeworx. An agent can immediately tell what this tool does and how it differs from siblings.

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

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

Explicitly states when to use it ('best for broad/multi-part questions over structured data'), when not to ('For a single lookup use ask_pipeworx'), and when to prefer an alternative ('For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also explains depth-level behaviors, so an agent can select the right mode.

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. The description adds behavioral context: it returns top-N relevant tools with full schemas and examples, 'ready to call directly, no second schema lookup needed.' This complements the 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 a single paragraph that front-loads purpose and efficiently lists supported domains. Every sentence adds value (usage advice, output format). Could be slightly more structured, but it's appropriately sized for the information provided.

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 what is returned: 'names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also covers usage context and categories. Minor gaps (e.g., ordering of results) are acceptable.

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 6 parameters described). The description doesn't add new parameter details, but the schema itself includes examples (e.g., 'look up FDA drug approvals'). Baseline 3 is appropriate since the schema does the heavy lifting.

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: 'Find tools by describing the data or task.' It lists specific categories (SEC filings, FDA drugs, etc.) and explains the output (top-N relevant tools with schemas). It also distinguishes itself from sibling tools by advising 'Call this FIRST when you have many tools and want to see the option set.'

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and advises 'Call this FIRST when you have many tools available and want to see the option set.' While it doesn't explicitly state when not to use, the positive guidance is strong and clear.

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

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

Annotations already mark this as readOnly, idempotent, and non-destructive, so the description adds behavioral context beyond those. It discloses parallel fan-out across multiple upstream sources, the sources_used/sources_failed contract, that an empty section means genuine 'no data' rather than a bug, FDA-licensed biologics only, and the GDELT→GNews fallback. These details tell the agent exactly what to expect and how to interpret results.

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 information-dense, with the purpose and preference directive front-loaded before the detailed source/output enumeration. It lacks crisp paragraph structure, but every sentence contributes: examples, fan-out sources, return fields, no-data semantics, accepted inputs, and edge-case behavior. Minor redundancy with the schema's type/value explanation keeps it from a 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so comprehensively: CIK/company_name, resolved_from/resolved_to, recent_filings URIs, fundamentals, patents, contracts, FDA products, hiring, news, LEI, and the sources_used/sources_failed mechanism. It also covers fallback behavior, private-company handling, and expected empty sections, making the tool fully callable without external assumptions.

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 schema already contains rich descriptions for both 'type' and 'value', including the interchangeability of 'company' and 'ticker' and accepted forms (ticker, CIK, name). The description mostly restates this with examples and adds output-related resolution behavior (resolved_from/resolved_to), but it does not meaningfully expand the parameter semantics beyond the schema. 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 opens with concrete user phrasings ('Tell me about X', 'research Acme', 'company profile for Microsoft') and states a precise purpose: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact output sections (filings, fundamentals, patents, contracts, etc.), which sharply differentiates it from narrower single-source lookups and sibling tools like compare_entities or resolve_entity.

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 instructs 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' telling the agent when to select this tool instead of alternatives. It also addresses edge cases: a private company returns resolved:false with a notes line rather than a failure, and type accepts 'company' or 'ticker' interchangeably. This is strong when-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 destructiveHint=true and readOnlyHint=false, which the description aligns with by saying 'Delete'. The description adds no further behavioral details (e.g., irreversibility, side effects), but annotations carry the main burden.

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

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

Two sentences, front-loaded with the action, and zero waste. Every word is necessary and directly contributes to understanding.

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 one parameter and no output schema, the description fully covers purpose, usage, and parameter semantics. No gaps given 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% with one parameter 'key' described as 'Memory key to delete'. The description does not add meaning beyond what the schema already provides, 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 states 'Delete a previously stored memory by key' with a specific verb and resource. It also mentions siblings 'remember' and 'recall', distinguishing the tool's purpose from related tools.

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

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

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It could be improved by explicitly stating when not to use, but the guidance is clear and contextual.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds process details: fetching page, extracting title/description/key links, emitting markdown. No mention of error conditions or rate limits, but sufficient given 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?

Single paragraph, front-loaded with key action. Includes examples without being overly verbose. Could be slightly more structured but effective.

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, when to use, how it works (fetch, extract, emit), and output format (single text blob). No output schema exists, but description sufficiently explains return value. No missing aspects for this simple 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%, baseline 3. Description adds context that URL can be a specific landing page and explains default vs max for max_links. This adds value beyond schema descriptions.

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

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

Clearly states the verb 'generate' and the resource 'llms.txt file for any URL'. Distinguishes from sibling tools like ai_visibility_check by its specific output. Provides concrete examples of usage.

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

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

Lists explicit use cases (client indexing, personal project, competitor auditing) which guide when to use. Lacks exclusion criteria or alternatives, but context is sufficient for most agents.

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, etc. Description adds value by listing specific return fields and stating it returns caller's own subscriptions. 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?

Two sentences: first defines purpose and output fields, second provides usage guidance. 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?

With one parameter fully described in schema and output fields listed in description, the tool is fully specified for its simple read operation. 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% for the single parameter (include_inactive). The description does not add meaning beyond what the schema already provides, 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 uses specific verb 'List' and resource 'the caller's active subscriptions', and lists the returned fields (id, type, params, etc.). It clearly distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context and purpose.

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 value by detailing the specific metadata returned (compound count, sources, versions), which helps the agent understand the output 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?

The description is a single sentence that efficiently conveys all necessary information: what the tool returns and the specific items included. It is concise, front-loaded, and contains no redundant 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 that the tool has no parameters and no output schema, the description provides sufficient context about the return value, listing specific data points. It is complete for the complexity of 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?

The tool has no parameters, and the schema coverage is 100%. The description does not need to explain parameters; it appropriately focuses on the output. Baseline score of 4 applies since there are zero parameters.

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

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

The description clearly states that the tool returns MyChem.info build metadata, including compound count, annotation sources, and versions. It distinguishes itself from sibling tools by its specific informational purpose, as no other tool in the list retrieves system metadata.

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 implies usage for obtaining build metadata, but does not explicitly state when to use it versus alternatives. However, given that no sibling tool provides similar functionality, the context is clear enough for the agent to decide.

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 are all false and thus provide no safety profile, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and the claim-token workflow: 'Filing without an account returns a `claim_token`; pass it back later to read whether it was fixed and what changed.' It also states the human impact: 'The team reads digests daily and signal directly affects roadmap.' 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 every sentence earns its place; it front-loads the core purpose and then systematically covers usage, exclusions, claim-token mechanics, and limitations. It reads as a single dense paragraph rather than structured bullets, which could be slightly harder for an agent to parse, but it avoids waste and is appropriately scoped for a tool with nuanced behavior.

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

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

With no output schema, the description must explain return behavior, and it does: 'Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed and what changed.' It also covers rate limits, quota, and when not to use it. Given the tool's complexity (4 params, nested object, enums, no required params), the description fully equips an agent to invoke it correctly and interpret results, leaving no critical 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?

The schema already has 100% coverage with detailed descriptions for each parameter, so the baseline is 3. The description adds meaningful usage context beyond the schema: the claim_token parameter's purpose is explained as 'pass it back later... to read whether it was fixed and what changed,' and it instructs agents to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies how to fill context and message. This elevates it to 4, but not 5 since the schema already handles most semantics.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this tool from siblings like ask_pipeworx or query by narrowing scope to feedback about Pipeworx tools/packs, and enumerates the exact feedback types (bug, feature, data_gap, praise).

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

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

Explicitly states when to use: 'Use 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 gives a hard exclusion and alternative: 'ONLY for tools served by this Pipeworx connection... file it with that server instead,' plus a disambiguation check ('Pipeworx tool names are the ones this connection lists').

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 (read-only, idempotent, etc.), description adds data source (CF analytics-engine), privacy (no PII), and caching details (5min-1h). 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 concise yet thorough, front-loading the result and covering use cases, technical details, and caching. Every sentence adds value.

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 one optional parameter and no output schema, the description is fully complete, covering return values, usage context, and behavior.

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

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

Schema already describes the 'window' parameter with enum and description. The description reinforces the trade-off between short and long windows, adding value beyond the schema.

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

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

Description clearly states what the tool does: returns top tools, packs, and call volume over a window. It distinguishes from siblings like 'ask_pipeworx' by focusing on trending data of other agents' usage.

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 and explains window trade-offs (shorter for hot, longer for steady-state). Provides clear guidance on when to use without needing to state 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 indicate read-only and idempotent behavior. The description adds rich context: checks include monotonicity, partition sums, Jaccard similarity, placeholder filtering, and fill checks against live CLOB depth. 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 thorough and well-structured, but slightly verbose. Each sentence adds value, and the information density is high. Could be tightened 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?

Given the tool's complexity and no output schema, the description covers all necessary aspects: invocation modes, logic, edge cases, response structure, and fill-check caveats. Enough for an agent to use correctly.

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

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

Input schema has 100% description coverage for two parameters. The description adds value by explaining the behavioral difference between event and topic modes with examples, but schema already documents parameter meaning well.

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 arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three invocation modes (trending scan, event, topic) and distinguishes itself from siblings 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?

Provides explicit guidance on when to use each mode (event recommended for specific markets, topic for cross-event scanning). Includes when not to trade (realizable_edge_pp ≤ 0) and references alternative tool for custom sizing (polymarket_fill_risk).

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

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

Annotations indicate read-only, idempotent behavior. The description adds extensive behavioral context: caching policy (1h KV-level), response structure with segments and diagnostics, edge calculation details (e.g., Kelly caps, slippage handling), and excluded categories (Fed bets). 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 comprehensive but verbose, with extensive technical detail on model families and response fields. While front-loaded with purpose, the length could be reduced for quicker comprehension.

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

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

Despite no output schema, the description fully explains response structure (by_segment, diagnostics, fed_candidates), caching, parameter effects, and model behavior. Callers can understand capabilities, limitations, and how to interpret results without additional sources.

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 individual descriptions. The description further elaborates on parameter roles (e.g., tradeable-edge knobs, min_partition_leg_kelly usage) and interaction between parameters, adding meaning beyond the schema.

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

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

The description clearly states the tool scans top Polymarket markets and returns edge opportunities where Pipeworx data disagrees with market price, distinguishing it from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and multi-model discovery.

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 implies use for daily betting discovery ('what should I bet on today') and mentions caching, but does not explicitly state when not to use it or compare to alternatives like polymarket_arbitrage. Usage context is clear but 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?

Discloses behavioral traits beyond annotations: snapshot TTL (60-day), data gaps due to cache-miss, and detailed response structure. Annotations already indicate safe read-only, but description adds critical context about data freshness and limitations.

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

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

Description is informative but verbose with long sentences. Front-loaded with purpose, but could be more concise. Well-structured with sections but some 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?

Despite no output schema, the description fully explains the return format (tracked, expired, snapshot_dates) and edge cases (gaps, TTL). Covers all necessary context for a complex 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 detailed descriptions. The description adds minor context (e.g., default/max values) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: answering 'how long has this edge existed and is it shrinking?' and distinguishes it from sibling tools like polymarket_edges by focusing on persistence telemetry. Uses specific verb+resource structure.

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

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

Provides clear context on when to use: to differentiate between fresh and old edges. While it doesn't explicitly list exclusion cases, the context about edge aging implies usage scenarios.

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 substantial context: walks the order book ladder, returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and highlights risks like forced_directional_risk. No contradictions.

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

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

The description is long but all sentences add value, explaining modes, defaults, and risks. It is front-loaded with core requirements and purpose. Could be slightly more concise, but the length is justified given complexity.

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

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

Given the complexity (two modes, four parameters, no output schema), the description covers all necessary aspects: input requirements, behavior for each mode, output fields, and risk warnings. It is fully self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains side defaults (auto for basket based on partition sum), size_usd interpretation (max spend, target proceeds, settlement notional), and clarifies which parameter (market vs event) determines the mode.

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

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

The description clearly states the tool performs a realizable-vs-theoretical edge check against live CLOB order-book depth, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges. It specifies two modes (single-market and basket) and what each does.

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 when to use the tool: before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. Also warns about risks of partial basket fills converting arb into unhedged directional positions.

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 non-destructive, and the description substantially enriches that with important behavioral disclosures: compatibility_warning/codes can be non-empty on returned pairs, unknown legs are never paired, temporal_alignment null means 'could not compute' rather than aligned, and spreads are gross of Kalshi fees. 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 front-loaded and every sentence conveys real information, but it is a long, dense paragraph with inline caveats and repeated safety reminders. It could be more readable with headers, bullets, or shorter sentences, which would make the warnings easier for an agent 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?

With no output schema, the description carries full responsibility for explaining the response and behavior, and it is exceptionally complete. It covers both modes, output fields, compatibility code meanings, null semantics, skipped-leg counters, fee treatment, and the warning that pre-mapped topics are not automatically tradeable. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is high. The description adds value beyond the schema by explaining the interaction between `topic`, `kalshi_event_ticker`, and `polymarket_event_slug`, including the fact that explicit tickers override the topic-mapped side and that both modes run the same token-overlap matcher.

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 by clearly stating the tool's core purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It then explains two modes and what the response contains. It falls short of a 5 because it never explicitly distinguishes this tool from sibling alternatives such as 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 gives concrete guidance on when to use the `topic` shortcuts versus explicit `kalshi_event_ticker` + `polymarket_event_slug` pairings, and it notes that both modes use the identical matcher. It provides clear usage context but does not explicitly say when to prefer a sibling tool or when NOT to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. Description adds value by specifying the nature of returned data (aggregated cross-references) and accepted input varieties, but does not contradict annotations. No annotation 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?

Three sentences efficiently cover purpose, inputs, and use case. No unnecessary words; all sentences contribute directly to tool understanding.

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?

Description covers purpose, inputs, and output characteristics (cross-references to specific databases). No output schema exists, but description explains what is returned. Could mention pagination limits, but schema includes size parameter with description.

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

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

Schema coverage is 100% with each parameter described. Description adds concrete examples (e.g., 'aspirin', 'chembl.pref_name:aspirin') that enhance understanding beyond the schema definitions, justifying a slightly above-baseline score.

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

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

Description clearly states the tool searches MyChem.info for drugs/chemical compounds, specifies accepted input types (plain name, InChIKey, fielded query), and explains the output (aggregated hits with cross-references). It distinguishes from siblings by focusing on chemical entity resolution.

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 includes a use case ('resolve a drug name into structured identifiers') and gives example queries. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, missing an opportunity for clearer guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by disclosing that the retrieval is scoped to the agent's identifier, which is not in annotations. 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, each purposeful. Front-loaded with the core action ('Retrieve a value...'). No redundant words. Information density is high with zero 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 read-only tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and parameter behavior. No gaps remain for the agent to use it correctly.

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

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

Schema coverage is 100% for the single parameter 'key'. The description restates the behavior (omit to list all keys) but does not add new semantic details beyond the schema. 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 retrieves a previously saved value or lists all keys, with specific examples (ticker, address, research notes). It distinguishes from sibling tools 'remember' and 'forget' by describing its complementary role.

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

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

It explains when to use the tool: to look up stored context without re-deriving it. It also mentions pairing with 'remember' and 'forget'. However, it doesn't explicitly state when not to use it or provide alternatives beyond the sibling list.

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 key behaviors beyond annotations: the structure of returned alerts (source, citation_uri, payload), the effect of mark_read on subsequent calls, and that the feed is persisted. This adds significant behavioral context that annotations (readOnlyHint, idempotentHint) only imply.

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 composed of four concise sentences, each serving a purpose: stating the core function, describing return data and filters, explaining a parameter effect, and offering an alternative. Front-loaded with purpose, no redundant words.

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

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

Despite lacking an output schema, the description covers return data structure, parameter usage, and even an alternative access method. It is complete for a read-only polling tool, though it could explicitly mention sorting order (most recent first) and pagination behavior beyond the limit parameter.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (e.g., 'sec_8k' for type) and explaining the practical effect of mark_read, which is not fully detailed in the schema descriptions. This elevates it slightly above 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?

The description starts with a clear verb ('Pull') and resource ('fired events from your subscription feed'), precisely stating the tool's function. It distinguishes from siblings like 'list_subscriptions' by focusing on alert events and their persisted feed.

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 mentions that polling works fine and provides an alternative REST endpoint for scripts/dashboards, giving context on when to use the tool. However, it does not explicitly compare against sibling tools like 'recent_changes' or 'list_subscriptions' to guide selection.

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 confirm read-only, idempotent, non-destructive nature. Description adds behavioral details: multi-source fan-out, fallback logic, USPTO soft-fail, and return structure (changes grouped by source, total_changes, citation URIs). 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?

Description is thorough but slightly verbose. However, every part serves a purpose: examples, source list, fallback, parameter hints, sibling reference. Front-loaded with examples, making it easy to scan.

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 covers return format and sources comprehensively. Addresses complexity of multi-source feed with fallback and deprecation note. No missing context for agent to use 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 has 100% coverage, but description adds value by explaining since format (ISO vs relative shorthand) with examples, and clarifying value accepts ticker or CIK. Significantly enhances parameter understanding beyond schema.

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

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

Description explicitly states 'change feed for a company' and provides concrete usage examples ('what's new with X'). It differentiates from sibling entity_profile by stating when to use the static profile instead.

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 clear when-to-use guidance via example queries and explicit when-not-to-use reference to entity_profile. Mentions fallback behavior between GDELT and GNews, aiding decision-making.

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

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

Annotations already provide idempotentHint, but description adds useful context about persistence scoping, authentication differences, and retention limits. Missing explicit mention of overwrite behavior, but overall transparent.

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

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

Four sentences in one paragraph, each serving a distinct purpose: what, when, scope, persistence. No filler, perfectly sized.

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 all essential aspects: purpose, usage hints, persistence, pairing with other tools. Could mention key length limits but not necessary for typical use. Adequately 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%, providing clear parameter explanations. Description adds some example keys but does not significantly extend beyond schema. 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?

Description clearly states the tool saves data for later reuse, using specific verb 'save' and resource 'data' in key-value pairs. It distinguishes from siblings 'recall' and 'forget' by mentioning them as companions.

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 when to use ('when you discover something worth carrying forward') with concrete examples. Also mentions authentication persistence and anonymous session timeout, providing clear context for usage decisions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses internal cascading lookups, graceful degradation of LEI/FIGI enrichment, exact-ticker versus name-search resolution, coverage of non-equity instruments, ISIN-to-LEI mapping, and the drug result format including a citation. This is substantial behavioral context an agent needs.

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

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

The description is front-loaded with purpose and usage guidance, and each clause carries behavioral or semantic value. However, it is a long single paragraph with a promotional tail ('using resolve_entity replaces 2-3 manual lookups') that is not strictly necessary for invocation. Still well above the minimum viable length.

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

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

For a two-parameter read-only tool with no output schema, the description covers input formats, return identifiers, supported types, and failure behavior (graceful degradation). It does not explicitly describe ambiguous-result handling such as candidate lists or unresolved fields, but this is a minor gap rather than a critical one.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds that company input accepts ISIN, explains exact-ticker vs name-search behavior, and clarifies drug accepts brand or generic names. This goes beyond the schema, though the schema's value description already covers most input guidance, so a 4 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 opens with concrete example queries and states exactly what the tool does: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It names the verb (resolve), the resource (entities/names), and the output (canonical identifiers), and distinguishes itself from siblings by framing itself as the prerequisite ID lookup. Supported types and their specific identifiers are enumerated.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups. However, it does not explicitly name alternative tools or state when not to use it, so it stops short of full routing guidance.

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

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

Annotations already indicate the tool is read-only, idempotent, open-world, and non-destructive. The description adds behavioral context: it probes each entity, ranks by score, and returns specific fields (score, confidence, signal density). No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence contributes meaning. No redundancy or filler.

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

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

Given the tool's complexity (4 parameters, no output schema), the description adequately covers functionality, input requirements, return fields, and use case. It is sufficiently complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds value by clarifying that the first entity is treated as the 'subject' for narrative and that models defaults to 'workers-ai'. This goes beyond the schema definitions.

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, probes each with ai_visibility_check, and produces a ranked list. It gives a concrete use case example ('does Claude know about us as well as our competitors?') and distinguishes itself from the sibling ai_visibility_check by being a multi-entity batch comparison.

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

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

The description explains it is useful for competitive AI-marketing audits and provides an example question. However, it does not explicitly state when not to use this tool versus other siblings like compare_entities, though the specific purpose 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?

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description enhances this by detailing composite fan-out, partial failure behavior ("degrade gracefully"), and timing ("first measurement ... can take 5-30s"). No contradictions with annotations.

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

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

The description is a single, dense paragraph that front-loads the purpose and covers usage, return fields, limitations, and error behavior. It is efficient but slightly dense, deserving a 4 rather than 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?

No output schema exists, so the description carries the full burden. It lists exact return fields (e.g., is_latest, bundle_kb_gz, tree_shakeable), mentions per-advisory details, links, and alternative versions. It also addresses error scenarios (sources_failed, timing). This is comprehensive 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 description coverage is 100% with clear parameter descriptions (package name with scoped support, version with default). The description mentions version defaults and alternative packages but adds minimal semantic value beyond the schema. Baseline 3 applies.

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

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

The description begins with a clear, specific verb+resource: "Composite 'should I add this npm package to my project' check." It explicitly lists the data sources (deps.dev, bundlephobia) and output fields, distinguishing it from sibling tools that do individual lookups or 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?

The description states "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'," providing clear, actionable guidance. It notes the NPM-only limitation and directs other ecosystems to deps.dev:version, but does not elaborate on when to avoid this tool in favor of a sibling.

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, etc. The description adds rich behavioral details: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars with truncation flag), and output format (passages with offsets). 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?

Description is compact but packed with essential details. The first sentence is a clear purpose statement. Some technical details (BGE-base-en, 500-char windows) could be slightly reordered, but 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?

Given no output schema, the description fully explains return shape (passages, character offsets, similarity scores). It covers edge cases (truncation at 200K chars, flagging). Pairs with sibling tool for comprehensive workflow. All behavioral aspects are disclosed.

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

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

Schema coverage is 100% but description adds context beyond schema descriptions: examples for query ('supply-chain risk', 'drug interactions with warfarin'), clarifies 'text' as 'document text to search inside', and explains 'limit' as max passages. This adds meaning for an AI agent.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and specifies the tool's role: retrieving top-N passages with character offsets and similarity scores. It effectively distinguishes from siblings like ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a when-not-to-use hint by pairing with ask_pipeworx_grounded for grounding. The alternative tool is named, making selection 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?

The description adds significant behavioral context beyond annotations: it explains that subscriptions persist only with OAuth, details delivery channel constraints (SMS cap, webhook auto-disable), and mentions that webhook secret is returned once. No contradictions with annotations.

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

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

The description is relatively long but each sentence adds necessary detail. It is front-loaded with the core purpose and prerequisites, then details types and delivery. Slightly verbose but efficient 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?

Given the tool complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: purpose, prerequisites, parameter details, behavioral traits, and delivery options. It is fully sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but the description provides extensive additional semantics: type-specific parameter examples, constraints (e.g., sponsor or condition required for clinical_trial), and delivery validation rules. This greatly aids correct parameter usage.

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

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

The description clearly states the action 'Create a proactive monitoring subscription' and the resource 'live-data event stream'. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation. The verb 'subscribe' is specific and the scope is well-defined.

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 includes prerequisites (Pipeworx OAuth account) and provides examples of when to use each type. However, it does not explicitly state when not to use this tool or mention alternatives, which would be helpful for an agent to decide between this and similar tools like ask_pipeworx or recent_alerts.

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 behavioral context by detailing the output format (category-bucketed example questions) and noting it draws from a live catalog. It does not contradict annotations.

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

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

The description is front-loaded with the essential purpose and example queries. It includes necessary details about output and usage in a structured manner, though it is slightly verbose with the list of categories.

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 one optional parameter and no output schema, the description covers input, output, use case, and when to use it. There are no missing critical details.

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

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

Schema coverage is 100%, and the description elaborates on the 'topic' parameter by listing example values and explaining how omitting it gives the full spread. This adds meaning beyond the schema's description.

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

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

The description clearly states the tool's purpose: it returns category-bucketed example questions with tool+argument shapes for answering them. It lists specific user intents (e.g., 'what can you do?', 'getting started') and distinguishes itself from sibling tools by being the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also explains optional topic filtering. Although it doesn't contrast with all sibling tools, the guidance is clear and 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?

Adds significant value beyond annotations: ownership enforcement, deactivation (not deletion), and linkage to recent_alerts for historical data. Annotations already indicate idempotency and non-destructiveness, which are consistent.

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 that are front-loaded with the main action and minimal waste. Every sentence provides essential information.

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

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

For a simple tool with one parameter and no output schema, the description covers the purpose, constraints, and side effects comprehensively. References to recent_alerts and ownership enforcement provide full context.

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

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

Schema coverage is 100% with a clear description for the single required parameter 'id'. Description does not add additional semantics beyond the schema, so baseline score 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 the action ('Cancel a subscription by id.') and distinguishes from sibling tools like subscribe and list_subscriptions by mentioning ownership enforcement and deactivation instead of deletion.

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?

Specifies when to use (unsubscribe with id) and constraints (ownership enforcement). Implicitly contrasts with subscribe and recent_alerts but lacks explicit alternatives or when-not-to-use scenarios.

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 hints, but the description goes beyond by explaining important edge-case semantics: could_not_verify is NOT evidence and carries a verification_error; unsupported means no source is covered. It also reveals the routing logic between SEC EDGAR/XBRL and the grounded pipeline, which is not visible 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 dense and packed with useful information, with no obvious fluff. It is front-loaded with examples and purpose. However, it is a long single paragraph rather than structured bullets; breaking it into sections could improve scanability, but the content justifies its length.

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

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

Even without an output schema, the description fully explains return values (verdict categories, actual value, citation, reasoning), error semantics for could_not_verify, and the difference between unsupported and refuted. It covers the tool's scope and edge cases comprehensively for a tool of this complexity.

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

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

Schema descriptions already cover both parameters (claim and tolerance_pct) at 100%. The description adds value by clarifying how tolerance_pct overrides claim wording and its default behavior, plus providing example claims in the schema. It reinforces and extends the schema meaning without substantial gap.

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

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

The description opens with concrete natural-language examples and explicitly states the verb+resource: verifying factual claims against authoritative sources. It clearly differentiates from sibling tools (e.g., ask_pipeworx, deep_research) by focusing on claim verification and by mentioning the two distinct pipelines for financial vs. other claims.

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

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

It gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also contrasts the financial fast path with the grounded pipeline, and notes that this tool replaces 4–6 sequential calls. However, it does not explicitly name alternatives or state when NOT to use it, which would push it to a 5.

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