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, idempotentHint, and openWorldHint. The description adds context about routing to 5,563 tools, returning structured answers with citation URIs, and being 'one fast call' that works on every tier. No contradictions, but the added behavioral detail is moderate.

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 verbose but well-structured, starting with the key directive 'PREFER OVER WEB SEARCH' and then systematically covering use cases, alternatives, and examples. It earns its length but could be trimmed slightly without losing clarity.

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

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

Given the tool's complexity (routing among thousands of sources), the description covers purpose, usage, alternatives, examples, and response format (citation URIs). It does not have an output schema, but the description compensates by explaining the return structure. No significant 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 description coverage is 100% with all parameters described as 'Alias for question.' The description does not add further meaning beyond the schema; it only provides examples in the schema's examples array, not in the description text. This meets the baseline for high coverage.

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

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

The description explicitly states to 'PREFER OVER WEB SEARCH' and lists a wide range of specific data domains (SEC filings, FDA drug data, etc.), clearly distinguishing it from general web search and sibling tools like ask_pipeworx_grounded and deep_research.

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 ('START HERE for most questions', 'PREFER OVER WEB SEARCH') and when-not-to-use ('Step up only when needed' for grounded or deep research), with concrete examples of queries that fit the tool.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it falls back to nothing (it's a full working router), and explains the experimental nature and current parity with the stable version. This provides useful context beyond what annotations already convey, though it doesn't detail what happens if a candidate is active (e.g., potential behavioral divergence).

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

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

The description is a single dense paragraph that efficiently conveys purpose, usage context, current state, and fallback behavior. It is front-loaded with the key 'beta version' concept. Could be slightly more structured with line breaks, but the information density is appropriate.

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 output schema is absent, the description could explain the return shape (e.g., same as ask_pipeworx). However, the annotation and sibling context are rich, and the description sufficiently covers the tool's experimental nature, current parity, and usage intent. For a complex routing tool with 6 parameters (all aliases), this is largely 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% and the single required parameter 'question' is well-described in the schema with aliases. The description adds no parameter-specific details beyond what the schema already provides. The baseline of 3 applies since the schema does the heavy lifting.

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

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

The description clearly states 'Beta version of ask_pipeworx' and specifies it's a universal router to the same 5,563 tools. It distinguishes itself from the stable ask_pipeworx by being the experimental edge. The verb 'ask' plus 'pipeworx' as the resource is implicit from the name, and the sibling list includes ask_pipeworx, so differentiation is provided.

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 tells the agent to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the context of candidate routing improvements. It implies this tool is for testing new routing logic while ask_pipeworx is the stable default. The sibling 'ask_pipeworx' is directly referenced.

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

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

Annotations only declare readOnlyHint=true and destructiveHint=false. The description adds critical behavioral detail: costs one extra LLM call than ask_pipeworx, returns specific refusal reasons (not_in_source, no_tool_match, tool_error, etc.), and describes the exact success/refusal response shape.

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 adds value: purpose, cost tradeoff, response structure, and when to use alternatives. No wasted words, front-loaded with the critical 'hallucination-resistant' label. Compact and structured.

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

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

Fully complete: explains what the tool does, how it differs from its sibling, its cost tradeoff, exact return format including both success and refusal cases, and expected use cases. No output schema needed given the detailed description of the return shape.

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 description doesn't need to add much. It correctly notes that multiple aliases (q, text, input, query, prompt) map to question, but the primary semantics of 'question' are already clear from the schema description. Minor value added.

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 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers only from tool results. Distinguishes from sibling ask_pipeworx by naming it and describing the extra extraction step.

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 (for high-stakes answers that will be quoted/cited/acted on) and when not to (prefer ask_pipeworx for casual lookups). Lists concrete use cases: financial verdicts, legal claims, medical lookups, public statements.

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?

Annotations already set readOnlyHint and idempotentHint to true, so the agent knows this is a safe operation. The description goes far beyond annotations by explaining the multi-faceted decomposition, parallel tool routing, citation format (with pipeworx:// URIs), gap handling (gaps[] array), contradiction detection, hop field, and semantic excerpting. It also discloses cost/account requirements (depth:'thorough' needs paid plan) and expected latency (15-90s). 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 with information but front-loaded with critical details (account requirement, alternative tool). Every sentence adds value. A slight deduction for being relatively long (over 200 words), though the complexity of the tool 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?

Given the tool's complexity (2 parameters, no output schema, no nested objects), the description fully covers behavior, constraints, output format, edge cases (e.g., empty gaps), and contextual alternatives. It is complete for an agent to make an informed decision.

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. However, the description adds significant meaning beyond the schema: it clarifies that the depth parameter affects facet count, hop recovery, and contradiction scanning, and explains how the question is decomposed naturally. This elevates the score to 5.

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

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

The description clearly states that deep_research performs multi-source research across structured data sources, explicitly distinguishing it from open-web search. It specifies the verb ('research'), resource ('Pipeworx's structured data sources'), and scope ('grounded multi-source'), which differentiates it from sibling tools like ask_pipeworx.

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

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

The description provides explicit when-to-use guidance, including scenario examples like 'compare X and Y's regulatory + financial exposure'. It also states when NOT to use it (e.g., for breaking news or single lookups) and names the alternative tool (ask_pipeworx). This makes the usage guidelines exceptionally 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 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?

Annotations already indicate safety (readOnly, idempotent, non-destructive). The description adds significant behavioral context: fans out across multiple data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), returns specific fields, soft-fails for patents, and explains input format. This goes beyond what annotations provide.

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

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

The description is a single paragraph that packs a lot of information efficiently. It front-loads example queries and then covers all important details. Some structure like bullet points could improve readability, but it remains concise with no wasted words.

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

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

Despite having no output schema, the description fully explains the return value: CIK, company name, filings (with URIs), fundamentals (sorted), patents (with sunset note), news (via GDELT→GNews fallback), and LEI. It also covers input constraints, prerequisites, and limitations, making the tool's behavior completely transparent.

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 reinforces schema details (ticker or zero-padded CIK, type only 'company') and adds the advice to use resolve_entity for names, which is helpful but not essential beyond the schema.

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

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

The description clearly states the tool's purpose: to return a full cross-source profile of a US public company in one parallel call. It uses specific verbs like 'tell me about', 'research', 'brief me', and distinguishes itself from sibling tools like resolve_entity and compare_entities by emphasizing holistic view and parallel execution.

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

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

The description provides explicit when-to-use guidance: prefer this tool over chaining single-pack lookups when the user asks for a holistic view. It also specifies when not to use: if only a name is provided, use resolve_entity first. Example queries are given, and limitations like patent soft-fail are noted.

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?

Beyond annotations (read-only, idempotent), the description details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and their meanings, and warns about real spreads being rarer than shortcuts suggest. This goes far beyond minimal 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 well-structured, front-loading the purpose and modes, then detailing response fields and warnings. While dense, every sentence adds value, but could be slightly trimmed for brevity.

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 and three parameters, the description is remarkably complete: it explains return structure (leg-by-leg prices, top spreads), temporal alignment, and warning conditions. No aspect of tool behavior is left ambiguous.

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

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

With 100% schema coverage, the description adds context by explaining the two parameter modes, listing the 10 topic macros, and clarifying that explicit tickers override topic. This meaningfully enhances the schema's documentation.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question, distinguishes it from single-venue siblings like polymarket_edges by explicitly calling it 'Cross-venue spread'. It also outlines two modes, making its purpose specific and actionable.

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 two usage modes (topic shortcuts vs explicit tickers) and includes a strong caveat that pre-mapped topics often return warnings, guiding users to not rely solely on them. However, it does not explicitly compare to other tools like polymarket_arbitrage, leaving some inference to the 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 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 mark readOnly/idempotent/openWorld. The description adds substantial behavioral detail: unresolved identifiers are declared under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully to EDGAR only, and ISINs are mapped to legal entities via GLEIF. These behaviors are not inferable from 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 information-dense and begins with practical examples, but it is a single long paragraph with heavy parentheses and embedded clauses. It earns its length, though it could be restructured into shorter sentences for easier scanning.

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

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

With no output schema, the description effectively enumerates the returned fields for both company (CIK, ticker, company_name, LEI, ownership, FIGI) and drug (RxCUI, ingredient, brand, citation), plus the unresolved handling and fallback behavior. This gives an agent sufficient understanding of the tool's capabilities and output.

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

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

Even with 100% schema coverage, the description enriches parameter meaning by explaining that company `value` may be an ISIN, that the tool resolves ISINs to the legal entity via GLEIF, and that each type returns a specific set of identifiers and citation links. This goes beyond the schema's `value` description.

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

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

The description states a clear goal: resolve user-spoken names to canonical/official identifiers. It lists example queries and enumerates supported types (company, drug) with specific outputs. The phrase 'Use FIRST...' distinguishes it as the entry point for ID lookup among siblings.

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

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

States 'Use FIRST whenever you have a name but need an ID' as explicit when-to-use guidance, and notes it replaces 2-3 manual lookups. However, it doesn't explicitly mention when not to use or name alternative tools, so it stops short of full exclusion guidance.

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

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

The description 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.