Fas

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral details: default model is free, Anthropic requires a separate key and direct payment, and it details the return structure (per-model score/confidence/signals/raw_response plus combined view). 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 paragraph of moderate length, with each sentence adding value. It front-loads the core purpose and follows with optional details and use cases. It could be slightly more structured (e.g., bullet points), but it remains clear and efficient without redundancy.

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

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

Given no output schema, the description adequately explains the return format. Annotations cover safety. All parameters are described in schema and enriched in description. Use cases are listed. The tool is simple enough that the description provides sufficient context for correct invocation and understanding of output.

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

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

Schema coverage is 100%, so parameters are well-described. The description adds value beyond the schema by explaining the default model, the optional nature of models parameter, and how 'context' disambiguates. It also clarifies that _apiKey is only needed for Anthropic and that it's passed directly.

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 verbs ('probe', 'score') and identifies the resource ('LLMs', 'business/brand/product/topic'). It clearly differentiates from siblings by stating use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', which are distinct from other tools like 'compare_entities' or 'scan_competitor_ai_presence'.

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

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

The description explicitly states when to use: for AI-marketing audits, brand checks, and competitive monitoring. It provides context about default model and optional Anthropic probe with a BYO key. However, it lacks explicit 'when not to use' or direct comparisons to sibling tools, though the use case context implicitly guides 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 readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it fills arguments automatically, returns stable pipeworx:// citation URIs, and acts as the default entry point. This gives the agent a strong sense of what will happen when invoked.

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 most important usage rule and is organized into mechanism, triggers, examples, and alternatives. It is somewhat long and contains minor redundancy in the alternative-routing guidance, but the density of actionable information justifies the 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 tool with a single natural-language input and no output schema, the description is complete enough: it explains what input to provide, what the tool does with it, what the return will include (structured answer with citation URIs), and which sibling tools to use instead in specific situations. No critical information needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by specifying that the input should be a natural-language factual question, providing trigger phrases and concrete examples. This goes beyond the schema's simple 'question or request' description and helps the agent formulate the right kind of query.

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

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

The description states a precise role: route a natural-language question to the appropriate one of 5,798 tools across 1,517 verified sources and return a cited structured answer. It clearly differentiates itself from web search and from siblings by describing its routing behavior and citation output.

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

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

The description is explicit about when to use the tool: prefer over web search for factual questions about current/historical data, and use for trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It also names specific alternatives and when to choose them: ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part fan-out, and ask_pipeworx_beta for early access.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: candidate improvements are enabled live, the last candidate was retired on a specific date, results are compared against the stable router, and it 'falls back to nothing' meaning it is a fully functional router, not a stub. This transparency goes beyond the annotations.

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

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

The description is compact and front-loaded, leading with the beta identity and router scope. Each sentence earns its place by covering current state, usage, and a clarification that this is a full working router. It is slightly dense but not verbose or redundant.

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

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

For a tool whose output shape matches ask_pipeworx, the description covers the essential context: what it is, how it differs, when to use it, and its current runtime state. It does not describe return values, but the 'same response shape' clause covers that by reference. It is sufficiently complete for an agent to decide when to invoke it.

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

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

The description does not discuss parameters, but the input schema has 100% description coverage. The schema thoroughly documents the question parameter and its aliases, so the description does not need to add parameter details. A baseline score of 3 is appropriate given the schema handles the burden.

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, an identical universal router with the same 5,798 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by enabling candidate routing improvements under test, making the purpose and scope immediately understandable.

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

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

The description explicitly states when to use the tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also notes that no candidate is currently active, so it matches ask_pipeworx exactly right now. It does not explicitly mention the grounded alternative or state when not to use it, but the 'experimental edge' label implies caution for production use.

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

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

Annotations already signal readOnly, idempotent, non-destructive, and open-world behavior, and the description adds substantial context: the structured return shape with evidence and confidence, the explicit refusal object with enumerated refusal reasons, and the extra LLM call cost. 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?

Packed but every sentence earns its place: mode, routing behavior, return contract, refusal reasons, use cases, and cost tradeoff. The key distinction is front-loaded before implementation details, making the tool selectable at a glance.

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

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

Despite having no output schema, the description fully explains success and refusal return shapes. It covers routing, grounding guarantees, when to prefer the sibling, and the failure modes an agent might encounter. Nothing critical 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 description coverage is 100%, and the schema fully documents the single question parameter plus its aliases. The description adds context about what the question is used for but does not need to redefine parameter meaning, so the 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?

Purpose is explicit: this is the hallucination-resistant, grounded answer mode that routes through ask_pipeworx's tool selection but extracts answers only from tool results. It clearly distinguishes itself from ask_pipeworx and describes a specific verb/resource combination: answering high-stakes questions with evidence and refusals.

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

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

Provides explicit when-to-use guidance: use when answers will be quoted, cited, or acted on, or when facts must not be invented. It names ask_pipeworx as the alternative for casual lookups and gives the cost tradeoff, so an agent can make an informed routing decision.

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

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

Annotations only indicate read-only, open-world, idempotent behavior. The description adds extensive behavioral details: resolution, classification, fan-out, response shapes, safety constraints (low-confidence short-circuit, closed markets), resolution-rule risk, and tradeability checks. 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 well-structured with sections and front-loaded purpose, but it is verbose with many specific examples and internal details. It is not concise but is organized, making it relatively easy to parse.

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

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

Given the tool's complexity and lack of output schema, the description covers all critical aspects: input types, classifiers, fan-out behavior, response shape, resolver contract, parent event extraction, news fields, safety, and resolution rules. It is complete for an agent to understand and invoke the tool 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 baseline is 3. The description includes examples and explains parameter usage (e.g., market can be slug/URL/text), but this largely mirrors the schema descriptions. No significant additional semantics beyond what the schema provides.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data in one call. It specifies verb+resource and distinguishes from sibling tools like polymarket_edges by giving usage examples such as 'should I bet on X' and explaining the full fan-out process.

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 ('Use for ...') and implies when to use this tool (when you have a specific market, slug, URL, or question). It does not explicitly state when not to use it or compare directly to siblings, but the context is clear.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds rich behavioral details: company type pulls latest 10-K with off-calendar fiscal year handling, drug type pulls FAERS and FDA data, results sorted by primary metric, and returns 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 front-loaded with examples and key guidance. While somewhat long, every sentence adds value. Structure is relational with semicolons and dashes; could be more concise but not overly verbose.

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?

Comprehensive for a tool without output schema: covers both entity types, data sources, sorting behavior, capacity limits (2-5), and mentions return format (paired data + citation URIs). Adequate for agent to understand what it returns.

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 (100% coverage). Description adds meaning beyond schema: explains what each type enum does (company financials vs drug data), specifies values as tickers/CIKs for company, and reinforces constraints (2-5 items). Adds context for parameter interpretation.

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 'side-by-side comparison of 2–5 companies or drugs' with example queries and data sources. It clearly distinguishes from sequential lookups by saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

Provides explicit usage context: 'Compare X and Y', 'vs', 'which is bigger', 'rank these companies', etc. Tells agent to prefer this tool over sequential lookups and implies when not to use (if not comparing).

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/openWorld/idempotent annotations, the description reveals auth requirements and paid tier, non-open-web limitation, never-invents gaps, citation resolvability, latency expectations, and semantic excerpting of large records. These are concrete behavioral facts an agent otherwise could not infer. 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 dense and long, but front-loaded with the account requirement and primary action before detailed depth behavior. Some details could be tightened, yet most sentences add unique information; the structure is logical rather than rambling.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: findings packet fields, gaps[], contradictions[], hop, citation_uri, and latency. It also covers auth, alternatives, and depth semantics, making it complete for an agent to decide whether and how to call the tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by tying depth values to paid access, contradiction scans, gap recovery, and latency, and by giving sample natural-language questions for the question parameter. It does not formally restate each parameter but complements the schema 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 names a specific verb and resource: grounded multi-source research over Pipeworx's 1,517 structured data sources in one call, decomposing questions and returning a findings packet. It also draws clear boundaries by stating 'this is NOT open-web search' and distinguishing itself from single-lookup and single-source sibling tools.

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

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

Explicit guidance is given for when to use this tool (broad/multi-part questions over structured data) and when not to: use ask_pipeworx if not signed in or for a single lookup, and use search_within for a search inside one known source. The depth parameter is mapped to appropriate usage contexts (thorough for multi-step chases, standard for gap recovery).

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false. The description adds behavioral context: returns top-N tools with full schemas and examples, results ready to call directly. This enhances understanding beyond annotations.

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

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

Description is two sentences, front-loaded with purpose and followed by context. Efficient but could be slightly more concise without losing clarity. 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 discovery tool with 6 parameters (many aliases) and no output schema, the description covers what it returns and when to use. Missing details like pagination or ordering are minor. Adequate for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant details about individual parameters; it focuses on the query concept and aliases. Schema already describes each parameter adequately.

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

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

The description clearly states the verb 'Find tools' and the resource 'tools', and distinguishes from siblings by positioning it as a meta-tool for discovering other tools. Sibling tools like 'deep_research' or 'bet_research' are specific domain tools, while discover_tools is for browsing available tools across domains.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and provides a list of example domains. Additionally instructs 'Call this FIRST when you have many tools available and want to see the option set', giving clear 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?

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already set, the description adds substantial behavioral context: fan-out across sources, soft-fail on USPTO sunset, expected empty FDA sections, sources_used/sources_failed semantics, and private-company resolved:false behavior. There is 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 the tool is complex and nearly every clause carries distinct behavioral or routing information. It is front-loaded with examples and the 'ALWAYS PREFER' directive; the rest is a structured enumeration of output sections and edge-case behavior. Some trimming of examples could improve conciseness, but it earns 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?

With no output schema, the description fully compensates by enumerating each return section, explaining fallbacks and failure modes, clarifying empty results, and specifying input resolution behavior. An agent has enough information to call this correctly across ticker, CIK, and company-name inputs.

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 value beyond the schema by giving concrete examples ('AAPL', '0000320193', 'Moderna'), emphasizing zero-padded CIKs, explaining that type values are interchangeable, and detailing what happens for private companies. This is a meaningful enhancement over the schema alone.

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

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

The description opens with concrete user phrasings and states the core function: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this from 'chaining single-pack SEC/XBRL/news lookups' by explicitly telling agents to prefer it for holistic views.

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 when-to-use rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It does not name specific sibling tools like compare_entities or deep_research, nor state when not to use it, but the guidance is actionable for the holistic-research case.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it returns commodity IDs, descriptions, and categories, and that it is used with other tools, but no additional behavioral traits beyond annotations. Moderate added value.

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 long, front-loaded with the primary action, and contains no unnecessary words. Every sentence earns its place.

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

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

Given the presence of an output schema, the description appropriately covers the purpose and return fields. It also provides context on how to use results with related tools. Complete for a search tool with annotations.

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

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

Schema coverage is 100% with descriptions for both parameters (search and category). The description does not add further meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches agricultural commodity codes and names, returning IDs, descriptions, and categories. It distinguishes itself from sibling tools by mentioning integration with fas_production, fas_exports, and fas_imports.

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

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

The description explicitly states that results should be used with fas_production, fas_exports, and fas_imports, giving clear context on when to use this tool. It does not mention alternatives or when not to use it, but the guidance is sufficient.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, which the description reinforces by stating it returns data. The description adds value by specifying the nature of the returned data (volumes, values, partner details) 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 extremely concise: two sentences plus a useful hint, all front-loaded with the core purpose. No wasted words.

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

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

Given the presence of an output schema, the description does not need to detail return fields. The parameter descriptions are complete, and the guidance for commodity codes is sufficient. The tool is well-contextualized among siblings.

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

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

Schema coverage is 100% with clear descriptions for all parameters. The description adds context beyond the schema by recommending use of the sister tool for codes, and examples illustrate usage. This elevates from baseline 3 to 4.

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

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

The description clearly identifies the tool's purpose: checking US agricultural exports by commodity and destination, and returning volumes, values, and trade partner details. It uses a specific verb ('Check') and resource, and distinguishes itself from siblings like fas_imports and fas_commodity_codes.

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 advises using fas_commodity_codes to find commodity codes, providing useful guidance for preparation. It implies when to use this tool (exports) versus alternatives (imports) but does not explicitly list exclusions or when not to use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds that it returns import volumes, values, and source country details, offering some 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?

Two sentences, front-loaded with purpose and output, zero waste. Every sentence earns its place.

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

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

Output schema exists, so return values are covered. Description covers purpose, output type, and a cross-tool hint. For a simple query tool with 4 parameters and 1 required, it is fairly complete, though optional year parameters are not highlighted.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no param-specific detail beyond the schema, but provides overall output context.

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

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

The description uses a specific verb ('Check') and resource ('US agricultural imports by commodity and origin country'), clearly distinguishing it from sibling tools like fas_exports and fas_production.

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 to use fas_commodity_codes to find commodity codes, guiding appropriate usage. Lacks explicit when-not-to-use comparisons with siblings, but provides clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds value by enumerating the types of data returned (production, consumption, inventory, trade flows), which helps the agent understand the output. No contradictions.

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

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

The description is a single sentence that packs relevant information. It is front-loaded with the verb 'Get' and the resource. Could be slightly more structured but is acceptable.

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 presence of an output schema (though not shown) and comprehensive annotations, the description covers the essential return fields and main usage. It does not explain behavior for multiple years or pagination, but it is mostly complete for a data retrieval tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters well. The description adds that the tool returns data 'by commodity and country' and implies country is optional for world totals, but this is already in the schema. Little additional 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 it returns production, consumption, inventory, and trade flows by commodity and country. It is specific about the data retrieved. However, it does not explicitly differentiate from sibling tools like fas_exports, which also cover trade flows, so clarity could be improved.

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

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

No guidance on when to use this tool versus alternatives such as fas_exports or fas_imports. The description does not mention prerequisites, exclusions, or context for appropriate use.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about deleting sensitive data, but does not disclose additional behavioral traits like what happens if key doesn't exist. It adds minimal value beyond annotations.

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

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

Three efficient sentences: first states purpose, second gives usage contexts, third links to sibling tools. No redundant information.

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

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

Given a simple tool with one parameter, good annotations, and no output schema, the description fully covers purpose, when to use, and relationship to siblings.

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

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

Schema has 100% coverage for the single parameter 'key' with a clear description. The tool description only repeats 'by key' without adding new semantic information, so baseline 3 applies.

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

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

The description clearly states the tool deletes a previously stored memory by key, using specific verb 'Delete' and resource 'memory'. It distinguishes from siblings by mentioning pairing with 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also advises pairing with remember and recall, providing clear context and 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds that it fetches the page, extracts info, and emits markdown, which is consistent but doesn't provide additional behavioral details (e.g., rate limits, caching).

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

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

Three concise sentences with no wasted words. Front-loaded with the core purpose, followed by use cases and output format. Each sentence earns its place.

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

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

Given no output schema, the description explains the output clearly (text blob ready for site-root/llms.txt). It covers input, process, output, and use cases. Annotations and schema cover safety and parameters well.

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%. The description mentions max_links but doesn't add syntax or constraints beyond the schema. Baseline 3 is appropriate as the schema already documents both parameters fully.

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

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

The description clearly states it generates an llms.txt file for a given URL, targeting AI crawlers. It specifies the action (generate), the resource (llms.txt), and the output format. This distinguishes it from sibling tools, none of which are similar.

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

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

The description lists three explicit use cases (client indexing, personal project, competitor audit). It lacks explicit when-not-to-use instructions or alternatives, but the use cases are clear enough.

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

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

Description aligns with annotations (readOnly, idempotent, non-destructive) and adds return field details. 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 extraneous words.

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

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

Simple tool with one optional param; description lists all return fields and provides usage guidance. Fully adequate.

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

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

Schema covers the only parameter fully (100% coverage). Description does not add extra meaning beyond schema.

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

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

Clearly states 'List the caller's active subscriptions.' and lists returned fields, distinguishing it from sibling tools like subscribe/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: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides helpful context but no explicit when-not-to-use.

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

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

Despite annotations all being false, the description discloses rate limits (5/day), quota exemption, the claim_token return flow, and the team's daily digest process. It fully informs the agent of side effects and follow-up behavior without needing annotation hints.

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

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

Every sentence carries essential information, front-loaded with purpose, then usage, exclusions, token mechanics, and limits. It is long but dense, with zero filler, making it appropriately sized for the tool's complexity.

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

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

The description fully compensates for the lack of an output schema by explaining the return token and how to later retrieve resolution status. It covers purpose, usage boundaries, rate limits, and follow-up, leaving no significant gaps for an agent to reason about.

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%, yet the description adds crucial meaning beyond the schema: the claim_token can be used standalone with no other arguments, and message content should describe issues in terms of Pipeworx tools rather than pasting end-user prompts. This enhances an already well-documented schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools like ask_pipeworx by scoping feedback to Pipeworx tools only, and explicitly contrasts with other MCP servers' 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?

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and an explicit exclusion with an alternative action ('file it with that server instead'). This level of directional guidance exceeds that of typical tool descriptions.

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?

Disclosures beyond annotations: self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h. No contradiction with annotations (all safe/idempotent).

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

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

Concise single paragraph with front-loaded output, then use cases, then technical details. Every sentence earns its place.

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

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

Given simple input (optional enum, no output schema), the description fully explains what, why, and how. 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 100%, description adds value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, exceeding schema info.

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 returns top tools, top packs, and total call volume over a recent window. Distinguishes from sibling tools like discover_tools by specifying it shows what other AI agents are calling.

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

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

Lists three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and notes window behavior. Does not explicitly contrast with sibling alternatives, but the context is clear enough.

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

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

Annotations declare readOnlyHint: true, idempotentHint: true. The description adds extensive behavioral context: monotonicity checks, partition sum verification, Jaccard similarity filter, placeholder filter, and fill check against 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 long but well-structured, front-loading the core purpose then detailing modes and internal checks. Every sentence adds value, though some sections (like FILL CHECK) could be slightly condensed.

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 the response structure (opportunities array, partition check, fill check). It also references sibling tools (polymarket_fill_risk) for additional context. Complete and self-contained.

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

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

Schema coverage is 100% with descriptions for both parameters, but the description adds rich semantics: event mode walks child markets, checks date-axis/threshold-axis ordering, partition check; topic mode searches related events and performs cross-event comparator. This goes far 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific behaviors, differentiating it from siblings like polymarket_edges or 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?

The description explicitly says when to use each parameter: no args for trending scan, event for a specific market, topic for cross-event scanning. It provides examples for both parameters. It doesn't explicitly state when not to use, but the guidance is clear and actionable.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description extensively details behavioral aspects: three model families, edge calculations, Kelly sizing, cache duration, diagnostics, and edge case handling (e.g., Fed candidates). 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 well-structured with clear sections for model families, knobs, and response structure. Front-loaded with purpose. Every sentence adds value, though slightly verbose for a concise definition.

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 (9 parameters, detailed model logic, no output schema), the description is comprehensive. It explains return structure, diagnostics, caching, and filter criteria, leaving no obvious gaps for an agent to understand usage.

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 3. The description adds substantial meaning beyond schema descriptions, especially for parameters like max_spread_pp and min_liquidity with practical guidance on usage. It compensates for the lack of output 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 Polymarket markets for opportunities where Pipeworx data disagrees with market price, using the verb 'scan' and specific resource. It distinguishes from siblings like polymarket_arbitrage by focusing on edge detection.

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 'Built for "what should I bet on today"' implying the use case. While it doesn't explicitly state when not to use, the sibling context provides alternatives. A clear usage context is provided.

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

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

Annotations declare read-only, open-world, idempotent behavior. The description adds value by explaining snapshot TTL (60-day limit), cache-miss-driven snapshot creation, and that decay is computed from daily closes not intraday. This goes beyond annotations.

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

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

The description is moderately concise given the amount of detail. It front-loads the core purpose and then systematically explains response fields and limits. A bit long but justifiably so for a complex output with no schema.

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

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

Despite having no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and their fields. It also covers limitations (TTL, cache-miss behavior, decay computation). This makes the tool fully understandable without additional documentation.

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

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

Both parameters have full schema descriptions (100% coverage). The description adds default values and constraints (days default 14, max 30; window default '1wk'). This provides slight added value, but substantial work is already done by 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and specifically answers 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series and persistence rather than current edge data.

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 implicitly provides usage context by comparing fresh vs. aged edges, indicating when to use this tool for historical analysis. However, it lacks explicit guidance on when not to use it or alternative tools, though the context is clear enough for an AI agent.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds behavioral details: walks order book ladder, returns top_of_book, vwap_fill_price, slippage, verdict, and basket-specific outputs. Warns about unhedged directional risk from partial fills. 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 long but well-structured with line breaks, case differentiation, and front-loaded core purpose. Each sentence adds essential information; minor redundancy could be trimmed.

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; description thoroughly explains return values for both modes (top_of_book, vwap, slippage, shares_filled, verdict, etc.). Covers edge cases (thin legs, forced directional risk). Complete given tool complexity and annotations.

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

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

Schema covers 4 parameters with 100% description coverage. Description adds significant context: explains side defaults for both modes, size_usd interpretation (spend vs target proceeds vs settlement notional), and modes of market/event parameters. Goes well 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 clearly states it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' Specific verb and resource. Differentiates from siblings by mentioning it should precede polymarket_arbitrage and polymarket_edges 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 states when to use: before acting on arb signals or trades above $500. Provides when-not warnings (thin books, partial basket fills). Explains single-market vs basket modes and default behavior.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations by disclosing that Kalshi fees are not modeled, spreads are gross not net, pairs may carry compatibility warnings even when returned, unknown legs are never paired, and temporal_alignment null means something specific. This is exceptional behavioral disclosure.

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

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

The description is long and dense, but it is well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS, codes, fees_note) and front-loaded with the core purpose. Some redundancy exists around compatibility codes, but the organization helps an agent parse the details without losing focus.

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 comprehensively explains response semantics: prices, top_spreads_pp, flags, compatibility codes, skipped counters, temporal_alignment, and fees_note. An agent has nearly everything needed to interpret results correctly and avoid common misuses.

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 three optional parameters at 100% coverage. The description adds meaning by explaining that topic auto-fetches matching events, explicit tickers override the mapped sides, and both modes run the identical matcher. This goes beyond the schema, though the schema does much of the work.

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

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

The description opens with a precise definition: cross-venue spread between Kalshi and Polymarket for the same resolving question. It names the exact resource and computation, and the detailed content distinguishes it clearly from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The tool clearly explains two operational modes (topic shortcuts vs explicit ticker/slug) and when each applies, including the warning that pre-mapped topics often return warnings and are not inherently tradeable. It does not explicitly name sibling tools as alternatives, but the usage context is strong enough for an agent to select and invoke it correctly.

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 destructiveHint=false, so the safety profile is clear. The description adds scope (anonymous IP, BYO key hash, account ID) which is valuable context beyond the annotations.

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

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

Three concise sentences, each earning its place: first states purpose, second explains use case, third adds scope and pairing. No redundancy or waste.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers all essential aspects: purpose, usage, scope, and relation to siblings. Annotations provide safety profile. Complete.

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

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

Schema coverage is 100% (key property described). The description adds that omitting key lists all keys, which clarifies the optionality and behavior, 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?

The description specifies the verb 'retrieve' and 'list', the resource 'value previously saved', and explicitly distinguishes from siblings 'remember' and 'forget'. It clearly states the dual behavior based on presence of key argument.

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 says 'Use to look up context the agent stored earlier... without re-deriving it from scratch' and mentions pairing with remember/forget. It doesn't explicitly list when not to use, but provides clear intent and scoping details.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint=false. The description adds behavioral details: mark_read affects subsequent calls, polling is fine, and the feed is persisted. 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 front-loaded with the core purpose and efficiently covers return content, filtering, mark_read behavior, and an alternative endpoint. Some details are dense but not verbose.

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 5 optional parameters, no output schema, and thorough annotations, the description adequately covers what the tool returns and how to use it. It lacks explicit return format details but mentions key fields.

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

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

Schema coverage is 100%, so description adds value by explaining mark_read's side effect and providing an example for type (sec_8k). It reinforces the schema's meaning but doesn't fully compensate for missing detail on limit or unread_only.

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 pulls fired events from the subscription feed, specifies the return contents (source, citation_uri, payload), and distinguishes it from sibling tools like list_subscriptions or subscribe/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?

The description explains when to use with filter options (type, since) and mentions polling suitability and an alternative REST endpoint for scripts. It doesn't explicitly exclude usage for other contexts but provides enough context for appropriate use.

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

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

Annotations already cover readOnly, idempotent, destructive, and openWorld hints. The description adds behavioral context: fan-out to multiple sources, fallback mechanisms, and soft-failure for USPTO, which goes beyond annotations.

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

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

The description is a dense but efficient paragraph, front-loading with example queries. Every sentence adds value, though it is somewhat lengthy. Structurally well-organized.

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 details the return structure (changes grouped by source, total_changes count, citation URIs). It also covers alternatives and failure modes, making it complete for a complex multi-source tool.

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

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

Schema coverage is 100%, but the description adds significant value: explains 'since' format (ISO date or relative shorthand) and recommends '30d' or '1m', and clarifies 'value' accepts ticker or CIK. This enriches parameter understanding.

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

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

The description clearly states the tool's purpose: a change feed for a company in a date window, fetching from SEC EDGAR, GDELT/GNews, and USPTO. It uses specific verbs ('fans out') and distinguishes from sibling tool 'entity_profile' for static profiles.

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

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

Explicitly provides example queries and states when to use this tool vs 'entity_profile'. It also details fallback behavior (GDELT→GNews) and soft-fail for USPTO, giving clear context on usage.

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

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

Annotations already indicate write operation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds value by detailing memory scoping by identifier and persistence behaviors, which are beyond the 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?

The description is concise—four sentences—front-loading the core purpose, then usage, storage details, and companion tools. Every sentence adds value without redundancy.

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

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

For a straightforward key-value write tool, the description is complete: it covers purpose, when to use, memory scope, persistence, and companion tools. No output schema is needed for a write operation, so the lack of return value details is 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%, with clear descriptions for both parameters ('key' and 'value'). The description does not add new parameter-specific details beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It uses a specific verb-resource combination and distinguishes itself from siblings like 'recall' and 'forget' by mentioning them. Examples of use cases (resolved ticker, target address, etc.) further clarify its role.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also differentiates between authenticated (persistent) and anonymous (24-hour) sessions, and recommends pairing with 'recall' and 'forget', giving clear context for choosing 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds substantial behavior beyond annotations: graceful degradation of LEI/FIGI enrichment, explicit `unresolved` fields, ambiguity handling via `figi_candidates`, and the internal cascade replacing multiple manual lookups.

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 densely informative, starting with user-phrase examples before moving to supported types and edge cases. Every clause contributes operational guidance, though the length pushes the limit of front-loaded clarity.

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

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

For a tool with two parameters, no output schema, but substantial hidden behavior, the description covers input variants, ambiguity resolution, enrichment failure, and internal multi-endpoint behavior. An agent has enough information to decide when to call it and how to interpret unresolved or candidate results.

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

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

Schema coverage is 100%, but the description adds critical semantics beyond the schema: accepted input forms include ISIN in addition to ticker/CIK/name, drug values accept both brand and generic names, and the value parameter must be the entity name only, with a concrete bond-issuer caveat. This materially improves correct invocation.

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 names the action ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input') and enumerates common queries. It does not explicitly differentiate from the sibling entity_profile tool, but the identity-to-ID focus is distinct.

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

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

It explicitly states 'Use FIRST whenever you have a name but need an ID' and enumerates supported types with concrete examples. It also gives boundary guidance, such as when a name matches multiple instruments it asserts nothing and returns figi_candidates.

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 meaningful behavioral context beyond annotations: it explains that the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This complements the annotations (readOnlyHint, idempotentHint) 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 concise (two sentences plus a parenthetical) and front-loaded with the primary action. Every sentence adds value, including the clarifying example. No redundant or extraneous text.

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

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

Despite having no output schema, the description explicitly lists the return fields (score, confidence, signal density). It covers the tool's purpose, parameters, and behavior adequately for its complexity. Minor omissions (e.g., error handling) are acceptable given good annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity is treated as the 'subject' and the rest as competitors, and provides examples for context and models parameters. This gives extra meaning beyond the schema descriptions.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using a specific verb ('Compare') and resource ('AI visibility across multiple entities'). It distinguishes from siblings by explicitly referencing the sub-tool ai_visibility_check and contrasting with single-entity probing, and gives a concrete use case for competitive AI-marketing audits.

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

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

The description provides clear usage context ('competitive AI-marketing audits') and an example question, implying when to use the tool. However, it does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entity scans.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds valuable behavioral details: fans out across two services, partial failures with graceful degradation, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts.

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 well-structured with front-loaded purpose, use cases, and constraints. Slightly verbose with parenthetical clarifications, but each sentence adds value. Could be trimmed slightly, but overall 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?

Despite no output schema, the description fully explains return values: summary block fields (is_latest, license, etc.), per-advisory detail, links, recent alternative versions, and failure behavior (sources_failed). Complete for a composite lookup tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning beyond schema: both package and version are already described with scoped packages mention and default behavior. No extra 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 clearly states it is a composite check for adding an npm package, listing specific checks (license, advisories, bundle size) and the question it answers ('is X safe/popular/small'). It distinguishes from siblings by being a composite tool that fans out across deps.dev and bundlephobia.

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

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

Explicitly says when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds critical details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and that each passage carries a character offset. This fully discloses 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 a single, well-structured paragraph that front-loads the core purpose and then adds important details about use cases, technical specifics, and pairing with siblings. Every sentence provides value without redundancy.

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

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

Given no output schema, the description fully explains what the tool returns (top-N passages, character offsets, similarity scores). It covers the cap, truncation behavior, embedding model, and even how it pairs with ask_pipeworx_grounded. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds meaning beyond property names: it explains 'text' as document text you already pulled, 'query' as natural-language with examples, and 'limit' as max passages. It also describes the output (passages with offsets and scores), which enhances understanding.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific examples (SEC 10-K, article), and explains the tool returns top-N passages with offsets and similarity scores. It distinguishes itself by noting it saves context and allows quote verification, which sets it apart from general search 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 'Use when the record is too big to cram into the prompt' and pairs the tool with ask_pipeworx_grounded for grounding over passages. While it doesn't list when not to use it, the positive guidance is clear and actionable.

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

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

Description states 'Create a proactive monitoring subscription,' implying a new subscription is created each call, contradicting the idempotentHint=true annotation. This is a serious inconsistency.

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 well-structured with clear sections (purpose, requirements, types, delivery). It is slightly verbose but front-loaded with key information. No unnecessary repetition.

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 the subscription types, delivery options, and prerequisites. It minimally mentions return value ('Returns the new subscription id'). With no output schema, more detail on response format would improve completeness.

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

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

Schema coverage is 100%, and the description adds valuable examples and context for each type's parameters and delivery options, going 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?

Description starts with 'Create a proactive monitoring subscription to a live-data event stream,' clearly stating the verb (create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions 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?

The description lists supported types and requirements (Pipeworx OAuth account), providing clear context for when to use. It does not explicitly state alternatives or when not to use, but context is sufficient.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already declare safety and nondestructive behavior. The description adds useful context about the return content (example questions with exact tool+argument shapes) and that it uses the live catalog. 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 thorough and front-loaded with example queries. Every sentence adds value, though it could be slightly more concise without losing information.

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

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

Despite having no output schema, the description fully explains what is returned (category-bucketed example questions, exact tool+argument shapes) and how to use it. All necessary context for an agent to decide to invoke the tool is present.

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

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

Schema coverage is 100% with a clear description for the single optional parameter. The description adds context by listing topic values and explaining behavior without arguments.

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 is an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It lists trigger phrases and explicitly distinguishes it from sibling tools like ask_pipeworx and entity_profile.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives for meta-tools. It also explains how to call with no arguments or with a topic parameter.

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

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

Discloses that the row is deactivated (not deleted) so historical events remain, and ownership is enforced. This adds value beyond annotations (which already indicate non-destructive mutation). 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?

Three efficient sentences, front-loaded with the key action. 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 parameter and no output schema, the description covers purpose, parameter usage, and behavioral effects completely.

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

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

Adds meaning by specifying that the id is 'returned by subscribe', providing context beyond the schema's description. Schema coverage is 100%, but this extra detail is helpful.

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 a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing the tool from siblings like 'subscribe' and 'list_subscriptions'.

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

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

States ownership enforcement ('you can only cancel your own subscriptions'), providing clear context on when to use the tool, though it does not explicitly mention alternatives or when not to use.

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

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

Goes far beyond the readOnly/idempotent annotations by disclosing the verdict categories and, critically, explaining that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also specifies what 'unsupported' means, the error structure, and the routing behavior, giving callers essential non-obvious context.

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

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

Although lengthy, every sentence earns its place: trigger phrases for routing, the use case, the dual-path behavior, the full verdict list with critical caveats, and the value proposition of replacing multiple calls. It is front-loaded with the most actionable information and avoids redundancy.

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

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

With no output schema, the description fully specifies the return payload (verdict set, actual value with citation, reasoning), error semantics for could_not_verify, and source-coverage meaning for unsupported. It also clarifies internal steps (entity resolution, comparison) so the agent understands exactly what the tool does and what to expect.

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 covers 100% of parameters with detailed descriptions, including tolerance range, default behavior, and use-case examples. The description adds only high-level context (percent-delta math, grounded pipeline) without introducing new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

Description clearly identifies the tool as natural-language claim verification with explicit trigger phrases and a specific verb ('validate', 'verify'). It distinguishes itself from siblings by detailing the two routing paths (SEC EDGAR fast path vs grounded pipeline) and the verdict-based output, making its scope unmistakable.

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

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

States a clear use condition ('Use whenever the agent needs to check whether something a user said is factually correct') and provides an internal decision rule for financial vs non-financial claims. It mentions replacing 4–6 sequential calls, implying efficiency benefits, but does not explicitly name alternatives or say when not to use this tool, stopping short of a 5.

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