Color

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by describing the output structure and clarifying cost implications for Anthropic probes, supplementing the annotations without contradiction.

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

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

Four sentences with clear front-loading: purpose first, then model configuration, output format, and use cases. Every sentence adds value with no redundancy or fluff.

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

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

Given full schema coverage, annotations, and no output schema, the description provides sufficient detail: what the tool does, how to use parameters, output format, and use cases. No gaps for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining default model behavior, BYO key requirement for Anthropic, and optional disambiguation context, enhancing agent understanding beyond parameter 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 specifies the verb 'probe', the resource 'LLMs', and the outcome 'score visibility (0-100) per model'. It clearly distinguishes from sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence' by focusing on multi-model visibility measurement.

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

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

Provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection with the free default and BYO key for Anthropic. Lacks explicit when-not-to-use guidance but overall context is clear.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, so the bar is lower. The description adds meaningful behavioral context: routes to one of 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and handles breaking-news routing. This goes beyond the annotations without contradicting them.

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

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

The description is long but information-dense. It front-loads the most critical guidance, uses examples effectively, and avoids fluff. Minor redundancy ('START HERE' and 'default entry point') is acceptable given the brevity of the message.

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

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

For a tool with no output schema, the description does a solid job explaining expected output (structured answer with citations) and coverage areas. It could briefly mention limitations or failure modes, but overall it is complete enough for an agent to decide when and how to invoke this 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%, and the schema itself documents the 'question' parameter with aliases. The description reinforces that the parameter is a natural-language question and provides examples, but does not add significant extra meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a clear directive: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists exact domains. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research for different use cases, making the tool's scope unmistakable.

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

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

Provides highly explicit when-to-use guidance, including trigger phrases ('what is', 'look up', 'find') and concrete examples. It also gives clear escalation paths: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

The description discloses key behavioral context beyond annotations: it is fully functional with no fallback, currently identical to stable because no candidate is active, and results are compared to the stable router. This complements the read-only/idempotent hints without contradiction.

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

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

The description is three sentences, each earning its place: it states the beta identity, current state, and usage guidance. It is slightly longer than necessary but remains efficient and front-loaded with the key distinction.

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 is a beta variant of ask_pipeworx, the description adequately covers its experimental nature, relation to the stable version, and current state. It does not explain the general router behavior, but that is inferred from the sibling tool and schema, making it sufficiently 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?

The schema already provides 100% coverage with descriptions for all six parameters, all aliases for the required 'question'. The description adds no parameter-specific information, so the baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes it from the stable sibling by highlighting experimental routing improvements and current state.

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 states when to use the tool ('when you want the newest routing') and notes it is experimental ('experimental edge'), implying the stable ask_pipeworx is the alternative. However, it does not explicitly specify when not to use it (e.g., in production), relying on the experimental label.

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

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

Adds significant behavioral detail beyond the readOnly/open/idempotent annotations: returns a structured payload with evidence, explicit refusal reasons (not_in_source, no_tool_match, etc.), and notes the extra LLM call overhead. No contradiction with annotations; the description complements them.

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

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

The description is dense but every sentence adds value: purpose, routing/execution, return format, usage context, and cost trade-off. It is well-structured and front-loaded with the most important intent, making it 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?

Despite no output schema, the description fully documents the return shape (success and refusal cases) and explains the routing behavior. It also provides usage boundaries and cost implications, making the tool comprehensible and actionable for an agent.

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

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

Schema description coverage is 100%; all six parameters are aliases for 'question' and are fully described in the schema. The description adds no additional parameter meaning beyond restating 'Your question in natural language.' Baseline of 3 is appropriate since the schema carries the full burden.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads' and differentiates it from sibling ask_pipeworx by describing its extraction behavior and explicit refusal mechanism. The verb+resource is specific and distinguishes it from other ask_* 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost trade-off ('Costs one extra LLM call'), providing clear guidance on choosing between alternatives.

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

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

The description extensively covers behavioral traits beyond annotations: resolver contract, parent event extraction, news fallback handling, safety short-circuits for low-confidence matches, closed market handling, wide spread warnings, and resolution-rule risk. No contradictions with annotations (readOnlyHint, openWorldHint, etc.).

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

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

The description is very long and dense, containing multiple paragraphs and many details. While well-organized with section headers, it could be more concise. Every sentence adds value, but the overall length may overwhelm agents. A shorter version with references to external docs might be more efficient.

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

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

Given the tool's complexity (multiple input types, fan-outs, response structures, edge cases), the description is remarkably complete. It covers all major aspects: input resolution, classification, evidence sources, response shapes with field descriptions, resolver contract, parent event extraction, news fallback, safety mechanisms, and resolution-rule risk. No output schema, but the description replaces it effectively.

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 substantial context: examples of valid inputs for 'market', explanation of 'depth' (quick vs thorough), and guidance for 'include_raw' (when to use true). The description enriches the schema's meaning, especially for the 'market' parameter.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). This distinguishes it from sibling tools like 'polymarket_edges' or 'validate_claim' by being the comprehensive research entry point.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of when fan-outs are triggered. However, it does not explicitly mention when not to use this tool or direct to alternatives, though the sibling list implies other tools for specific subtasks.

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

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

Annotations already mark it as readOnlyHint, idempotentHint, and non-destructive. The description adds 'Keyless, offline', which provides operational context (no API keys, no network calls) 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?

Two sentences; the first states the core purpose with specific standards, the second adds key behavioral notes. No redundant words, front-loaded with purpose. Ideal conciseness.

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

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

Given the low complexity (2 string params, no output schema), the description covers the computation (ratio and pass/fail) and operational nature (keyless, offline). It could explicitly mention output format, but the purpose is still clear. Annotations and schema cover the rest.

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 minimal descriptions ('Background color.', 'Foreground/text color.'). The description adds context (WCAG 2.1, pass criteria) but does not elaborate on valid color formats or constraints. Baseline 3 is appropriate as schema describes parameters and description adds tool-level 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 states a specific verb ('Compute'), a clear resource ('WCAG 2.1 contrast ratio'), and adds detail about pass/fail for AA/AAA text sizes. It clearly distinguishes from siblings like color_convert (format conversion) and nearest_color (named color lookup).

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

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

The description includes 'Keyless, offline' which hints at when to use (no auth or network needed) but does not explicitly state when not to use or mention alternative tools. It implies context for accessibility checking but lacks direct guidance on scenarios.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds 'Keyless, offline' which are behavioral traits not covered by annotations. No contradiction.

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

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

Two sentences, zero waste. The first sentence clearly states purpose and result, the second adds two important behavioral facts. Every word 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?

The tool has one simple parameter, no output schema, and rich annotations. The description covers what it does, input format, output, and key behavioral notes (keyless, offline). It is complete for the tool's simplicity.

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 detailed description of the 'color' parameter including examples. The description adds value by stating the output formats ('to all formats: HEX, RGB and HSL'), which is not in 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 verb 'Convert' and the resource 'color', and specifies input formats (HEX, rgb(), hsl(), CSS name) and output formats (HEX, RGB, HSL). It distinguishes from siblings like 'color_contrast' and 'nearest_color' which have different purposes.

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

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

The description states 'Keyless, offline', providing clear context that no API key is needed and it works offline. It does not explicitly say when to use versus alternatives, but the scope is clear enough for an agent to differentiate from sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it pulls from specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph but front-loaded with example triggers. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) 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 adequately explains return structure: paired data + pipeworx:// citation URIs, sorted by primary metric. It also covers data sources and special handling (fiscal years). For a tool with only 2 required parameters and no nested objects, this is very complete.

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

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

Schema coverage is 100% and describes both parameters. The description adds meaning beyond schema: it clarifies that for type='company' values should be tickers/CIKs and for type='drug' should be drug names, explains what data is fetched for each type, and reinforces the constraints on array length. This adds significant 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 specific verbs like 'compare', 'vs', 'head to head' and clearly states it performs side-by-side comparison of 2-5 companies or drugs in one parallel call. It distinguishes from sibling tools like entity_profile which would be used for single entity lookups.

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

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

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear context on when to use. It does not explicitly list alternatives, but the instruction to prefer this over sequential lookups is strong 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses many behavioral traits: account/payment requirements, parallel routing to 5,529 tools, return packet contents (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gaps[] and contradictions[], citation resolvability, semantic excerpting, and expected latency. 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 long but appropriately so for a complex tool with many caveats. It is front-loaded with the most critical information (account requirement, alternative tool). Some redundancy exists (e.g., 'NOT open-web search' emphasized, depth behaviors explained twice), but each sentence generally earns its place given 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 is remarkably complete for a tool with no output schema. It explains what the tool returns (findings packet, gaps[], contradictions[]), how it behaves (parallel routing, excerpting, hop iteration), when to avoid it (breaking news, single lookups), and operational details (timeouts, citation fetchability). This is comprehensive enough for an agent to select and invoke effectively.

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

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

Schema coverage is 100% for both parameters, so baseline is 3. The description adds extra value: question is clarified as accepting broad/multi-part queries ('decomposition is the point'), and depth includes the constraint that 'thorough' requires a paid plan, which is not in the schema. This enhances parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call'. It distinguishes from siblings by explicitly noting 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and breaking news. The verb 'research' plus the specific resource scope make it unambiguous.

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

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

The description provides explicit when-to-use guidance: use for broad/multi-part questions over structured data, use ask_pipeworx for single lookups and breaking news, and use ask_pipeworx if not signed in. It also explains depth-level tradeoffs (quick/standard/thorough) and when each is appropriate. This is exemplary usage 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 indicate idempotent, read-only, non-destructive behavior. The description adds critical behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' No contradiction with annotations.

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

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

The description is a single, dense paragraph that front-loads the purpose and immediately lists use cases. Every sentence adds unique value, including usage context and output format. 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 no output schema, the description adequately explains the return value: 'names, descriptions, and full input schemas (with curated examples).' It also covers input parameters via examples and aliases. The tool is simple, and the description covers all necessary aspects for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by providing examples of valid query strings (e.g., 'look up FDA drug approvals') and explaining that multiple aliases (q, task, search, description) are accepted. It could go further by clarifying that aliases are interchangeable.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes itself as a meta-tool for discovering other tools, unlike its siblings (e.g., search_within) which operate on 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?

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context for when and why to use it, effectively guiding the agent to use it as a discovery step.

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

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

Annotations already mark it as readOnly, idempotent, and non-destructive. Description adds that it fans out across multiple sources in one parallel call, returns specific fields like recent_filings with URIs, and notes that the USPTO source may soft-fail. 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?

Description is fairly long but front-loads with example queries and packs each sentence with useful information. Could be slightly more structured with bullet points, but every sentence earns its place. 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?

Given no output schema, description details what each returned field contains (e.g., up to 5 filings, fundamentals sorted, etc.). It also notes limitations (USPTO may soft-fail). Could mention any pagination or max results beyond what's implied, but overall provides sufficient context for an agent to use 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%. Description adds context: 'type' only supports 'company', 'value' must be ticker or zero-padded CIK, and names are not supported. It also provides examples like 'AAPL' and '0000320193', clarifying usage beyond 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 uses specific verbs like 'Tell me about', 'research', 'brief me' and clearly states it provides a 'full cross-source profile of a US public company' across multiple data sources. It lists exactly what is returned (CIK, filings, fundamentals, patents, news, LEI) and distinguishes from sibling tools like resolve_entity.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also states that names are not supported and advises using resolve_entity first if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already include destructiveHint=true and idempotentHint=true. Description adds context about memory deletion but does not significantly extend beyond the annotations. Acceptable for a simple operation.

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, concise and front-loaded with action and resource. No superfluous words.

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

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

For a simple deletion tool with one parameter and no output schema, the description covers purpose, usage scenarios, and relation to siblings. Missing return behavior but acceptable for this context.

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

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

Schema coverage is 100% and the schema provides clear description for the key parameter. Description adds 'previously stored' but doesn't add essential new 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 'Delete a previously stored memory by key,' using a specific verb (delete) and resource (memory). It distinguishes from siblings like 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 provides scenarios for use: stale context, task done, or clearing sensitive data. Also advises pairing with remember and recall. Lacks a direct 'when not to use' but is sufficiently clear.

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

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

The description details the tool's actions: fetches page, extracts title/description/key links, emits markdown. This adds behavioral context beyond the annotations (which indicate read-only, idempotent). 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 that front-loads the main purpose. It is informative but includes a list of use cases that could be slightly trimmed. Still, 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?

Given no output schema, the description explains the output format and typical placement. It covers main use cases and consequences. Minor omission: no mention of error handling or authentication requirements, but overall sufficient.

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

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

Schema coverage is 100% (both url and max_links described). The description does not add significant new meaning beyond the schema; it mentions url implicitly. 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 generates a production-ready llms.txt file for any URL, specifying the purpose (AI crawler indexing) and the output format. It distinguishes itself from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on a specific deliverable.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. This provides clear context for when to use the tool. However, it does not explicitly mention when not to use it or alternative tools, slight gap.

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 destructiveHint. The description adds value by specifying the default filter for active subscriptions and listing returned fields, providing additional behavioral context beyond the annotations.

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

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

The description is two concise sentences; the first states purpose and return fields, the second gives usage guidance. No unnecessary words, front-loaded with key information.

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

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

For a simple list tool with one optional parameter and rich annotations, the description covers all needed context: what it returns, default behavior, usage scenario. Output schema is absent but fields are described. Sibling context is clear.

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 only parameter (include_inactive). The tool description does not add further parameter semantics beyond what the schema already provides, so the baseline of 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?

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists return fields and distinguishes from sibling tools like subscribe/unsubscribe by stating its use for review and finding ids to cancel.

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 to review what you're monitoring before adding more or to find an id to cancel,' providing clear guidance on when to use the tool and directing to alternatives (subscribe, unsubscribe).

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

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

The description adds significant behavioral context beyond the annotations: it confirms the tool is offline and keyless, explains the distance metric (Euclidean RGB), and implies determinism. This complements the readOnlyHint and idempotentHint 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 a single, information-dense sentence. It conveys purpose, algorithm, and key features (keyless, offline) without any fluff. Every word 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 tool's simplicity (one parameter, no output schema), the description covers the essentials: what it does, how it works, and constraints. It could explicitly state the output format (e.g., 'returns a CSS color name string'), but the current wording implies that. Slight gap in return value specification.

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 repeats that the parameter accepts colors in HEX/rgb/hsl/name, which matches the schema description exactly. No additional meaning is provided 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 that the tool finds the nearest CSS named color using Euclidean RGB distance. It specifies the verb 'Find', the resource 'nearest CSS named color', and the algorithm. The note 'Keyless, offline' distinguishes it from sibling tools like color_convert or color_contrast, making the purpose unambiguous.

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

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

The description implicitly indicates when to use this tool (to match a color to a CSS named color) but does not explicitly contrast with siblings or state when not to use it. However, the purpose is so clear that an agent can infer usage context without difficulty.

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 sparse annotations (readOnlyHint: false, destructiveHint: false). It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token flow for anonymous filing and later retrieval, and the team's daily digest cadence. 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 flowing paragraph but every sentence carries distinct, high-value information: purpose, usage triggers, scope restrictions, token mechanics, rate limits, quota, and actionable instruction. No filler or repetition of schema fields; it is front-loaded with the central purpose.

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

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

Despite having no output schema, the description fully explains the input/output lifecycle: what happens when filing without an account (returns claim_token), how to later check status/resolution, and configurational constraints (rate limit, free quota). It proactively answers the likely questions an agent would have before calling this tool.

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

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

Schema coverage is 100%, so parameters are already well-described. The description adds meaningful extra semantics: it explains the claim_token round-trip ('Filing without an account returns a claim_token; pass it back later...'), and gives qualitative guidance for the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This enriches the schema explanations.

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 crisp, specific statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates feedback types (bug, feature, data_gap, praise) and clearly distinguishes this from sibling tools like ask_pipeworx or discover_tools by framing it as feedback to the team, not a query or discovery tool.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also strongly specifies the boundaries: 'ONLY for tools served by this Pipeworx connection' and instructs to file elsewhere for other MCP servers, with a practical way to disambiguate via tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and self-aggregating nature. This goes well beyond what annotations alone convey.

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 short paragraph with bullet points, front-loaded with the main outcome. Every sentence adds value—purpose, use cases, data source, caching, privacy. No redundant or unnecessary information.

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

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

For a tool with one optional parameter and no output schema, the description covers all necessary aspects: functionality, use cases, data source, caching, and privacy. It is fully self-contained and actionable.

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

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

The schema provides 100% coverage with an enum and description. The description adds meaning by explaining the effect of shorter vs longer windows and stating the default (24h). This enhances the semantic understanding beyond the schema.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It specifies the action ('Returns') and the resource ('what other AI agents are calling on Pipeworx'). The use cases further clarify its purpose, distinguishing it from siblings like ask_pipeworx or discover_tools.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming popular tool, seeing alignment) and explains how window selection affects output. While it doesn't explicitly state when to avoid using it, the context makes it 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 declare readOnly, openWorld, idempotent, non-destructive. Description adds context about fill checks against CLOB depth, partition filtering, and similarity thresholds, all consistent 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?

Long but dense with information; every sentence adds value. Could be slightly more structured (e.g., bullet points), but front-loads purpose and key usage.

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?

Very complete given complexity: explains inputs, behavior, response fields (opportunities, partition check, fill check), edge cases (placeholders, similarity), and references to sibling tool for sizing. No output schema, but return values are thoroughly described.

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 of parameters, but description adds significant meaning: explains modes, provides examples of slugs and topics, details behavior like URL acceptance and cross-event scanning logic.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) with specific behaviors, separating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each mode (trending scan, single-event, cross-event). Recommends 'event' for specific markets and explains cross-event use cases. Lacks direct comparison to sibling tools but references polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which the description supports by describing a read-only scan. The description adds extensive behavioral details: caching, Kelly sizing, slippage handling, edge computation, and diagnostics for empty segments, going well beyond annotations.

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

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

The description is very detailed and structured, but quite long (multiple paragraphs) with specific implementation details (e.g., alpha values for sports, exact Kelly caps). This exceeds what is necessary for an AI agent, slightly reducing conciseness.

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 9 parameters, no output schema, and complex response structure, the description is remarkably complete. It explains the top-level response segments, Fed bets, diagnostics, and how knobs affect filtering. Agents can fully understand behavior and edge cases 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?

All 9 parameters are documented in the input schema with descriptions (100% coverage). The tool description adds extra context for critical parameters like slippage_pp and min_partition_leg_kelly, explaining their practical implications 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 specifies the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and it is built for 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on pipeworx data disagreement and providing segmented responses.

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

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

The description states the tool is for discovering opportunities and implies usage for betting decisions, but does not explicitly mention when not to use it or compare to alternatives like polymarket_edge_tracker. However, the context is clear and the segmentation helps agents select appropriate segments.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds significant context: explains the meaning of edge age, details the response structure (tracked, expired, snapshot_dates), and discloses history limits (60-day TTL, from snapshot enablement). No contradiction with annotations.

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

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

The description is thorough but could be slightly more concise. It is well-structured with a clear intro, response breakdown, and limitations. Every sentence provides value, but some details (e.g., negative edge_pp_net = SELL YES) are dense.

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

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

No output schema exists, so the description must explain return values, which it does in detail: tracked array with time-series, first_seen, trend, decay_pp_per_day; expired array with lifespan_days; snapshot_dates. It also covers parameter effects and limits. Completely adequate 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% but the description adds default values, clamp range for 'days', and explains how 'window' selects snapshot families. It also ties parameters to the response (e.g., days affects lookback depth). This exceeds schema information.

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 provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It uses precise verbs like 'tracks' and identifies the resource (polymarket_edges snapshots), distinguishing it from siblings like polymarket_edges.

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

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

The description implicitly defines when to use it (when interested in edge history and decay), but does not explicitly state when to avoid it or mention siblings like polymarket_arbitrage or polymarket_fill_risk. However, the context is clear enough for an agent to decide.

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

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

Description adds detail beyond annotations: explains it walks the order book ladder, returns verdicts, and flags risk of directional exposure from partial fills. Annotations already indicate read-only, idempotent, non-destructive; description confirms and enriches.

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 sections for REQUIRES, SINGLE-MARKET, BASKET, and usage guidance. Every sentence adds value, though slightly verbose. Front-loads the core purpose.

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

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

Given no output schema, the description comprehensively lists return fields for both modes, explains verdicts, and addresses risks. Covers all necessary information for an agent to use 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?

All 4 parameters are described in the schema (100% coverage). The description adds mode-specific interpretation, default behaviors, and constraints (e.g., default side auto-detection in basket mode, size_usd interpretation for buys vs sells).

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

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

Clearly states the tool checks realizable vs theoretical edge against live CLOB depth, differentiates single-market and basket modes, and lists specific return fields. Distinguishes from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about the risk of partial basket fills converting arb into unhedged positions.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds extensive behavioral context: explains response structure (leg-by-leg prices, spread), safety fields (compatibility_warning, temporal_alignment), and the meaning of skipped_cross_type/subtype counters. No contradiction with annotations.

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

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

The description is thorough but somewhat lengthy. It is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides useful information, but a slightly tighter edit could improve conciseness.

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 absence of an output schema, the description fully explains the response structure, safety fields, and edge cases. It covers input parameters, modes, and interpretation of results, making it comprehensive for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by listing the exact topic shortcuts, explaining the format for explicit tickers, and clarifying that explicit params override topic-mapped sides.

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, a specific verb+resource. It distinguishes from sibling tools like polymarket_arbitrage (intra-venue) by focusing on cross-venue comparison.

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

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

Explicitly describes two modes (topic shortcuts vs explicit tickers) and when to use each. Warns that pre-mapped topics often return compatibility warnings, setting expectations about when the tool is not effective. Provides guidance on interpreting safety fields like temporal_alignment.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier, behavior when key omitted, and pairing with other tools. No contradictions.

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

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

Four sentences, front-loaded with core purpose. Every sentence adds value: retrieval, listing, usage context, scoping, pairing.

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

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

Tool is simple (one optional param, no output schema). Description covers retrieval, listing, scoping, and pairing. Complete for a read-only 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 description adds context about scoping and that omitting key lists all keys, beyond the schema's description.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', specifying the verb (retrieve/list) and resource (saved values/keys). It distinguishes from siblings 'remember' and 'forget' and explains scoping.

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: 'look up context the agent stored earlier... without re-deriving it from scratch'. Mentions pairing with remember and forget. No explicit when-not, but context is clear.

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

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

Goes beyond annotations by detailing return structure (source, citation_uri, payload), filtering options, and the side effect of mark_read. All behavior disclosed 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?

Three sentences plus a brief note, front-loaded with purpose. Every sentence adds unique value—no redundancy or fluff.

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

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

For a read-only tool with 5 optional parameters and no output schema, the description covers return fields, filtering, marking read, and alternative access. Completely sufficient.

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

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

Schema covers all parameters (100% coverage). Description adds value with examples (e.g., 'sec_8k') and clarifies behavior of mark_read and since. Exceeds baseline.

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

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

Description clearly states it pulls fired events from the subscription feed, with specific verbs and resource. It distinguishes itself from sibling tools like list_subscriptions and subscribe by focusing on retrieving alert events.

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 usage context by mentioning polling works fine and an alternative HTTP endpoint for scripts/dashboards. Could be more explicit about when not to use, but overall 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 indicate read-only, open-world, idempotent, non-destructive. The description adds significant behavioral context: parallel fan-out to multiple sources, fallback logic, and the USPTO soft-fail condition, 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 single dense paragraph but well-structured with clear examples and behavioral notes. It earns its length without being verbose, though some structuring (e.g., bullet points) could improve readability.

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 details the return structure (changes grouped by source, total_changes count, citation URIs). It covers edge cases (soft-fail, fallback) and provides sufficient context for agent 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% with descriptions for all 3 parameters. The description adds extra practical guidance, like suggesting '30d' or '1m' for since and examples of ticker/CIK formats, enhancing usability.

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 over a recent window, with specific sources and example queries like 'What's new with X'. It distinguishes from sibling tool entity_profile by contrasting static vs. dynamic changes.

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

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

Provides explicit guidance on when to use (monitoring recent changes) and when not to (use entity_profile for static profile). Also explains fallback behavior between GDELT and GNews, and the soft-fail for USPTO due to API sunset.

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 transparency beyond annotations by specifying scoping by identifier, persistence details (authenticated vs anonymous sessions), and idempotent behavior. Annotations already indicate idempotentHint=true and destructiveHint=false.

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 (4 sentences) and front-loaded with the core purpose. 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?

The description covers storage behavior, scoping, persistence, and pairing with sibling tools. No output schema exists, but the return value is implied by the pairing instructions, making it complete for a simple storage tool.

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

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

Schema coverage is 100% with descriptive parameter text. The description provides example values ('subject_property') but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific action and resource. It distinguishes from siblings like 'recall' and 'forget'.

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

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

The description provides clear guidance on when to use the tool ('when you discover something worth carrying forward') and pairs it with recall/forget for lifecycle management. It does not explicitly state when not to use it, but the context is sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: identifiers are labelled with their source, unresolved identifiers are explicitly listed under `unresolved`, LEI/FIGI enrichment degrades gracefully when external services are unavailable, and each call internally cascades through multiple endpoints. This goes well beyond what annotations convey.

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

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

The description is fairly long, but every sentence contributes meaningful detail: example queries, explicit usage instruction, per-type resolution behaviors, and graceful degradation. It is dense but not wasteful, though a bit more structure (e.g., bullet points for supported types) would improve readability. Still, it earns its length.

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

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

Given the tool's complexity (multiple entity types, multiple identifier sources, unresolved handling, graceful degradation) and the absence of an output schema, the description is remarkably complete. It explains what is returned for each type, how sources are labelled, how unresolved identifiers are surfaced, and what happens if external services fail. This fully equips an agent to use 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?

The input schema already covers both parameters with descriptions and examples (100% coverage). The description repeats these examples and adds context about the types of entities resolved (company vs drug), but this is more about output behavior than parameter syntax. With schema coverage at 100%, the baseline of 3 applies, and the description adds some but not substantial new parameter-level meaning.

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

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

The description clearly states the tool's function: resolving a user-spoken NAME to canonical/official identifiers. It provides multiple example queries and explicitly distinguishes it from sibling tools by saying 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource with clear scope.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that it replaces 2-3 manual lookups. However, it does not mention when NOT to use this tool or name alternative sibling tools like entity_profile, so it falls short of full exclusionary 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 cover safety (readOnly, idempotent, non-destructive). The description adds that it probes each entity with ai_visibility_check, ranks, and returns score/confidence/density. It also describes the special role of the first entity as 'subject'. 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 efficient sentences: first covers action and process, second gives example use case and output. No unnecessary words, 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?

Given no output schema, the description adequately describes the return type (ranked list with score, confidence, signal density). It could mention the ranking direction, but it's clear enough. Covers all key aspects.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds the nuance that the first entity is treated as the 'subject for narrative', which goes beyond the schema. It also mentions shared context but that's already in 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 uses a specific verb 'Compare AI visibility across multiple entities side-by-side' and clearly distinguishes from sibling tool ai_visibility_check by focusing on multiple entities and ranking. It states it probes with that tool, making the relationship explicit.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and implies when to use (comparing entities) vs alternatives like ai_visibility_check for single entities. It does not explicitly say when not to use, 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?

Discloses behavioral traits beyond annotations: it fans out to external services, may take 5-30s for bundlephobia's first measurement, degrades gracefully with partial failures listed in 'sources_failed'. Annotations only indicate read-only, idempotent, open-world, non-destructive.

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

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

The description is relatively long but every sentence adds useful information. It is front-loaded with the main purpose and structured logically. Could be slightly more concise but is still 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 details the return format (summary block, per-advisory details, links, alternative versions) and handles edge cases (partial failures, sources_failed). For a tool with 2 parameters and 100% schema coverage, this is sufficiently 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 already fully describes parameters (100% coverage). Description adds value by noting scoped packages are accepted for 'package' and default behavior when 'version' is omitted. This provides extra clarity beyond schema descriptions.

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

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

The description clearly states it's a composite check for evaluating npm packages across deps.dev and bundlephobia, addressing questions about safety, popularity, and size. It distinguishes itself from unrelated sibling tools by specifying the exact use case.

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 tells when to use (e.g., when asked 'is X safe / popular / small') and when not to use (other ecosystems like PyPI, Maven, etc., which fall under a different tool). Also provides context on partial failures and timeouts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds multiple behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and character offsets in results. 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?

Single paragraph, front-loaded with the core action and immediate use case. Every sentence adds value (purpose, scenario, technical details, pairing advice). No redundant words or filler.

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

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

Covers all aspects needed: purpose, when to use, technical details (embeddings, window, cap), output format (offsets and scores), and complementary tools. Despite no output schema, the description sufficiently informs the agent of return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds operational context: clarifies that 'text' is the already-fetched document, explains the output format (passages with offsets and scores), and notes the default limit of 5. This provides meaning beyond raw 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 performs semantic search inside a fetched record, with a specific verb ('search INSIDE') and resource ('a fetched record'). It differentiates from siblings like ask_pipeworx_grounded by explaining it operates on already-fetched text and returns passages with offsets.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both context and exclusion criteria.

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

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

Description adds rich behavioral details: OAuth requirement, type-specific filters, delivery channel specifics, webhook HMAC signing and auto-disable. However, it contradicts the idempotentHint annotation by stating each subscription returns a new id and a unique secret, implying non-idempotent 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 well-structured with a clear flow (purpose, prerequisites, types, delivery), but it is slightly verbose. Nonetheless, every sentence contributes 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?

Given the tool's complexity (3 params with nested objects, no output schema), the description covers purpose, return value, prerequisites, all types with examples, all delivery options with detailed behavior, limitations, and error handling (auto-disable). No gaps for agent 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%, and the description adds extensive context beyond the schema: type-specific examples (e.g., items codes for sec_8k), delivery format requirements, verification steps, and limitations (SMS cap, webhook auto-disable).

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 'Create' and the resource 'a proactive monitoring subscription to a live-data event stream', distinguishing it 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?

Provides explicit context: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), delivery channels (feed always on, optional email/sms with caps), and type-specific parameters. Does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that results are drawn from live catalog and include tool shapes, and it's the first step, which is helpful context beyond annotations.

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

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

Single paragraph covers synonyms, return content, optional parameter, and usage guidance. Front-loaded with synonymous questions. Slightly long but every sentence adds value; could be more structured but effective.

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

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

Despite no output schema, the description fully explains what is returned (category-bucketed example questions, tool+argument shapes) and mentions meta-tools. It is complete for an onboarding tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by stating 'call with no arguments for full spread, or pass topic to focus' and providing examples of topic values, clarifying usage 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 returns category-bucketed example questions with tool+argument shapes, and is the onboarding entry point. It distinguishes from siblings like ask_pipeworx and discover_tools by positioning itself as the first 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 'Use this FIRST when you do not yet know what Pipeworx can do' and describes optional topic focusing. Lacks explicit when-not-to-use or alternatives, 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?

The description reveals that the row is deactivated, not deleted, and that historical events remain available via 'recent_alerts'. This adds value beyond annotations (which only indicate non-destructive write). 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?

Two sentences with no fluff; all information is essential and front-loaded. 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 simple tool (1 param, no output schema), the description fully covers purpose, ownership, and effect. Links to 'recent_alerts' for context on history.

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 no extra meaning beyond the schema's parameter description ('Subscription id (uuid) returned by subscribe'). Baseline score is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') with specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions'), setting usage context. However, it does not explicitly state when not to use or list alternatives, though sibling names imply 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 only indicate that the tool is read-only, idempotent, and non-destructive. The description goes far beyond by explaining the dual pipeline, the meaning of each verdict, the crucial distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source), and the tolerance override behavior. This adds critical context for callers.

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 longer than average, but it is front-loaded with trigger phrases and every sentence provides necessary information about usage, behavior, return values, and edge cases. It is appropriately detailed for a tool with this complexity, though slightly 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?

Even without an output schema, the description fully specifies what the tool returns (verdict, value with citation, reasoning), explains error cases (could_not_verify with verification_error), and notes the efficiency benefit of replacing multiple sequential calls. This makes the tool self-contained and clear for an agent.

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

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

The input schema already provides detailed descriptions for both parameters (claim and tolerance_pct) with examples and defaults. The tool description adds some context (e.g., 'exact percent-delta math') but does not significantly improve parameter understanding beyond what the schema already offers.

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 identifies the tool as claim verification against authoritative sources, with a clear verb ('verify') and target resource ('claims'), and lists natural-language trigger phrases. It distinguishes itself from sibling tools by focusing on factual claim checking rather than general search or 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?

The description states clearly when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (fast path) and other claims (grounded pipeline). However, it does not explicitly name alternative tools or state when not to use, so it falls 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.