mhw

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

Annotations already indicate readOnly and idempotent; description adds details like default model (Workers AI), BYO key for Anthropic with cost implication, and output structure (score, confidence, signals, raw_response). No contradictions. Could mention rate limits or free tier limits.

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?

Five sentences with no redundancy. Front-loaded with the primary action and key details. 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 4 parameters, no output schema, and annotations providing safety profile, the description is complete. It covers what the tool returns, default behavior, optional parameters, and use cases. No gaps for an agent to misinterpret.

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

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

Schema coverage is 100% with parameter descriptions. The description adds value by explaining default model behavior for 'models' and the meaning of '@param _apiKey' (pass-through to Anthropic). However, it does not significantly enhance beyond schema for 'entity' and '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 clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It distinguishes itself from siblings like 'entity_profile' and 'scan_competitor_ai_presence' by focusing on AI awareness scoring across multiple models.

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

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

Describes use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Mentions default model and optional API key for Anthropic. Lacks explicit when-not-to-use or direct sibling comparison, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context: it returns structured answers with stable pipeworx:// citation URIs, works on every tier in one fast call, and notes the distinction for grounded vs. broad questions. 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 lengthy but well-structured: starts with a strong preference statement, then describes capabilities, usage guidance, and explicit alternatives. Every sentence earns its place. Could be slightly tighter but justified by the tool's complexity and the need to differentiate from many siblings.

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 (6 parameters, 1 required, many siblings, no output schema), the description is comprehensive. It covers purpose, when to use, examples, alternatives, and limitations. The agent has all necessary information to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with adequate descriptions for each alias parameter. The description goes beyond by providing guidance on what constitutes a good question (e.g., 'what is', 'look up', 'find') and including three concrete examples, adding significant value for the agent.

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

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

The description clearly states the tool's purpose: it routes questions to one of 5,008 tools across 1318 sources, returning structured answers with citation URIs. It distinguishes from siblings by positioning itself as the default entry point and explicitly contrasting with ask_pipeworx_grounded and deep_research.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH' for many domains, 'START HERE for most questions', and details when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). Includes concrete examples and covers when not to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it's a full working router, falls back to nothing, and describes the source-preference ranking behavior. No contradiction with annotations.

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

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

The description is dense with information but efficient. The first sentence immediately conveys the core purpose, and subsequent sentences add necessary detail. Could be slightly more concise, but 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 complexity of a beta universal router with thousands of tools, the description adequately covers the experimental nature, the specific ranking change, fallback behavior, and response shape (same as ask_pipeworx). No output schema, but the reference to 'same response shape' is sufficient. Complete for the tool's 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 all parameters are aliases for the 'question' field. The description states 'same arguments' but doesn't add new meaning beyond what the schema provides. The 'Your question or request' explanation is already in the schema. Baseline of 3 is appropriate since the description offers little additional semantic value for parameters.

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

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

The description clearly states it's a beta version of ask_pipeworx, a universal router with identical tools and arguments. It distinguishes from the stable version by highlighting candidate routing improvements and source-preference ranking. The verb 'ask' combined with 'Pipeworx Beta' makes the purpose specific and distinct from siblings.

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

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

The description explicitly says to use it 'exactly like ask_pipeworx when you want the newest routing' and explains the source-preference feature. It also mentions results are compared against the stable router, giving clear context on when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/true/true/false. The description adds details about return format (answer, evidence, confidence, source, fetched_at, refusal_reason) and explicit refusal modes (not_in_source, no_tool_match, etc.), as well as the cost (extra LLM call). No contradiction; adds behavioral context beyond annotations.

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

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

The description is concise (three sentences) and front-loaded with the core purpose. Each sentence provides unique value: first defines behavior, second details return format, third gives usage guidance. No filler.

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

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

Given the high schema coverage (100%) and rich annotations, the description covers the return format, refusal modes, and usage trade-offs. Despite lacking an output schema, the description fully explains what the agent can expect. Complete for a complex tool.

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

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

Schema coverage is 100%; all parameters are described in the schema with aliases listed. The description merely restates 'natural language' but adds no substantive 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 the tool is a hallucination-resistant answer mode for high-stakes reads. It specifies the verb ('extracts answer using ONLY what the tool result contains') and distinguishes itself from sibling ask_pipeworx by noting it costs one extra LLM call and should be used for cited/acted-on answers.

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

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

Explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' The description also mentions the trade-off (extra LLM call) and lists refusal reasons.

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 details behavioral traits including market resolution, classification, fan-out to data packs, response shapes, resolver contract, parent event extraction, news fallback handling, safety mechanisms for low-confidence matches, closed market handling, spread warnings, and resolution-rule risk. This adds significant value beyond the annotations (readOnlyHint, etc.) which are consistent.

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

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

The description is very long and dense, containing multiple paragraphs of technical details. While the content is valuable, it could be streamlined. The core purpose is front-loaded, but subsequent sections (e.g., RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR) are verbose. Shorter sentences and clearer sectioning would 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 tool's complexity (3 parameters, no output schema, intricate behavior), the description is exceptionally complete. It covers market matching confidence, fan-out examples, response shapes, parent events, news fallback, safety, spread handling, and cancellation rules. All essential behaviors are documented, compensating for the lack of output schema.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The tool description adds extra context: market parameter can be slug, URL, or question text; depth describes enum values; include_raw explains response size trade-offs. While the schema already covers basics, the description enriches understanding without redundancy.

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 action (research), the resource (Polymarket bet), and the outcome (evidence packet + comparison). It also provides usage examples and distinguishes itself from sibling tools through its unique focus on Polymarket bet analysis.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on inspecting market_match_confidence before trusting analysis. However, it lacks explicit when-not-to-use instructions or direct comparisons to sibling tools like polymarket_edges.

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 substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS/drug databases for drugs), specific metrics pulled (revenue, net income, cash, debt), and correct handling of off-calendar fiscal years. Result sorting by primary metric is also disclosed.

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 well-structured, front-loading common query patterns and then detailing behavior per type. Every sentence adds value, though the length is slightly above average. It earns a 4 because it efficiently packs information without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description provides a fair overview of return data ('paired data + pipeworx:// citation URIs per entity') and sorting. It does not detail the exact response structure, but the agent can infer it from the purpose. The description is complete enough for effective use.

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 enriches the schema with domain-specific guidance. For the 'type' parameter, it specifies what data is pulled for each enum value. For the 'values' parameter, it provides concrete examples (tickers/CIKs for companies, drug names for drugs) and clarifies constraints (2–5 items). This goes well beyond the bare 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 performs side-by-side comparisons of 2–5 companies or drugs. It lists natural language triggers ('compare X and Y', 'X vs Y', 'which is bigger') and distinguishes its parallel-call approach from sequential lookups, effectively differentiating it from sibling tools like entity_profile.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear when-to-use directive. It also gives query examples and explains the two entity types. Absent is a direct mention of when not to use it (e.g., if only one entity is needed), but the statement 'Replaces 8–15 sequential lookups' implies its suitability for multi-entity comparisons.

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 extensive behavioral traits beyond annotations: decomposition into facets, parallel routing, return format (findings, gaps, contradictions), hop iteration, depth specifics, timing, and source citation. No contradiction with annotations (readOnlyHint, 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 comprehensive but quite verbose (over 400 words). While front-loaded with the account requirement, it could be more concise by trimming some details that are already clear from the schema or annotations.

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

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

Given no output schema, the description fully explains the return value (findings packet with evidence, confidence, source, citation, gaps, contradictions), timing, account requirements, and fallback for not signed in. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains depth enum values (quick=3 facets, standard=5+gap recovery+contradictions, thorough=8+iterative+contradictions) and clarifies the question parameter as natural language, broad/multi-part acceptable.

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 grounded multi-source research across Pipeworx's structured data sources, distinguishing it from open-web search. It specifies the verb 'research' and resource 'structured data sources', and differentiates from siblings like ask_pipeworx.

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

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

Explicitly advises when to use this tool (broad/multi-part questions over structured data) vs alternatives (ask_pipeworx for single lookup or breaking news). Also mentions account requirements and depth-level recommendations.

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=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the return format ('top-N most relevant tools with names, descriptions, and full input schemas') and the 'ready to call directly' behavior. 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 front-loaded with the main purpose and key usage instruction. However, listing many domains in the first sentence makes it slightly less concise than it could be. 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?

No output schema is provided, so the description covers the return structure (names, descriptions, schemas) adequately. It also explains the tool's role as a first-step discovery tool, which is sufficient 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%, so baseline is 3. The description adds examples ('look up FDA drug approvals', 'analyze housing market trends') and mentions that the query accepts natural language and aliases, which adds practical value beyond the schema descriptions.

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

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

The description explicitly states 'Find tools by describing the data or task' and lists specific domains (SEC filings, financials, etc.), making the purpose clear and distinct from sibling tools. It also advises calling this tool first when many tools are available.

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 says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools and want to see the option set,' providing clear usage context. It does not explicitly state when not to use or list alternatives, but the guidance is strong enough to differentiate from siblings.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds detailed behavior: fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; returns specific fields (filings with URIs, fundamentals sorted), notes USPTO soft-fail (sunset May 2025), and mentions news fallback. No contradiction.

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

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

The description is moderately long but efficiently packs essential usage context, examples, and behavioral details. Front-loaded with examples, then details on sources and returns. Could trim slightly but overall well-structured.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description thoroughly explains the output structure (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and failure modes (soft-fail, fallback). Sufficient for an agent to understand returns.

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

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

Schema coverage is 100% with both parameters described. The description reinforces constraints (ticker or CIK only, no names, zero-padded CIK) and adds context that type is limited to 'company'. This adds value beyond the schema.

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

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

The description uses multiple examples ('Tell me about X', 'research Acme', etc.) and explicitly states it provides 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes from sibling tools like resolve_entity (for names) and compare_entities.

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

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

It directly instructs to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views. It also clarifies input restrictions: 'Pass ticker or zero-padded CIK — names not supported (use resolve_entity first).'

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful behavioral information beyond 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, no wasted words. The purpose and usage guidelines are 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and sibling pairing. Could mention return value or success behavior, but not critical.

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 'key' parameter. The tool description adds 'by key' but does not significantly enhance meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'a previously stored memory by key'. It distinguishes itself from sibling tools like 'remember' and 'recall' by specifying deletion.

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

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

Explicitly provides three use cases: stale context, task completion, clearing sensitive data. Also suggests pairing with 'remember' and 'recall', giving clear guidance on when to use this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: it fetches the URL, extracts content, and emits standard markdown. While it doesn't cover rate limits or potential blocking, it aligns with the annotations and provides sufficient transparency for an agent.

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

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

The description is compact: three sentences covering purpose, mechanism, and use cases. It is front-loaded with the primary action, followed by supporting details. No redundant or unnecessary sentences.

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 only 2 parameters (both described), no output schema, and simple read-only behavior, the description adequately explains what the tool does and what it returns ('single text blob'). It does not cover error handling or edge cases (e.g., unreachable URL), but given the tool's simplicity, it is reasonably 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 covers both parameters with descriptions (100% coverage). The description mentions 'fetches the page, extracts title/description/key links' but does not add meaning beyond what the schema already provides for 'url' and 'max_links'. The default (25) and max (50) for max_links are implied in the schema description, so no extra value.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file for any URL', and the specific outcome: a production-ready file for AI crawlers. It lists concrete actions (fetches, extracts, emits) and explicitly distinguishes from siblings by naming use cases like 'getting a client's site indexed by AI' versus alternative audit tools like scan_competitor_ai_presence.

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

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

The description provides clear use cases: getting a client site indexed, drafting for own project, or auditing a competitor. It tells when to use the tool, but does not explicitly state when not to use it or mention alternatives among siblings (e.g., scan_competitor_ai_presence for deeper audits). This is a minor omission.

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

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

Annotations already indicate safe read operation. Description adds specific return details (defense, elemental resistances, skill slots) and mentions practical use case, providing value beyond annotations without contradiction.

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

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

Two concise sentences: first states purpose, second adds return details. No wasted words, front-loaded with core functionality.

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 with one parameter and output schema present. Description mentions key return fields, which is sufficient given the schema and annotations. Complete for a read-only lookup tool.

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

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

Only one optional parameter 'limit' with full schema description (100% coverage). The tool description adds no further detail about the parameter, which is acceptable as the schema already documents it.

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

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

Description clearly states verb 'Find', resource 'armor', and scope 'by rank and type'. It also lists specific return fields, effectively distinguishing it from sibling tools like get_weapons and get_monsters.

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?

Implicitly clear that this tool is for armor queries, but lacks explicit guidance on when not to use it or alternatives. Sibling tool names provide context, but no direct 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by detailing the specific data returned (species, elements, ailments, weaknesses), which is useful 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 a single, clear sentence that efficiently conveys purpose and output. No unnecessary words.

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

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

Given the presence of an output schema and comprehensive annotations, the description provides sufficient context about what the tool returns and its intended use, making it complete for an AI 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 has 100% coverage with a clear description for the only parameter (limit). The tool description does not mention the parameter, so it adds no extra meaning. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches for monsters by name or type and specifies the returned data (species, elements, ailments, weaknesses), which distinguishes it from sibling tools like get_armor or get_weapons.

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

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

The description implies usage for hunt planning, but does not explicitly state when to use versus alternatives or provide exclusions. However, the context of sibling tools makes the purpose 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 contradicts the actual behavior: it says 'look up by name', but the schema only supports a limit, implying a simple list. Annotations (readOnlyHint, idempotentHint) are present and consistent with read operations, but the description adds a false impression of searching capability, which harms transparency.

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

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

The description is a single sentence, which is concise. However, the inaccuracy ('by name') undermines its effectiveness. It is structured appropriately but fails to convey correct 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?

Given the low complexity (1 optional parameter, output schema present, annotations clear), the description should accurately describe the tool's operation. It fails to do so by misrepresenting the input mechanism, leaving the agent without proper context for 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 coverage is 100% for the single 'limit' parameter, which has a clear description. However, the tool description adds no value for this parameter and instead introduces a misleading 'by name' pattern that doesn't exist in the schema. This reduces clarity rather than enhancing it.

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 'Look up', the resource 'Monster Hunter World skills', and the output details (descriptions, max ranks, level-by-level effects). It effectively distinguishes from sibling tools like get_armor, get_monsters, and get_weapons.

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 claims the tool looks up skills 'by name', but the input schema only has a 'limit' parameter with no name parameter. No guidance is provided on when to use this list tool versus alternatives. The description's claim about name lookup is misleading and unsupported.

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 strong behavioral hints (readOnly, idempotent, non-destructive). The description adds context about returned fields (damage, elements, rarity) but does not disclose additional behaviors like pagination or ordering. It does not contradict annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and resource. Every word contributes meaning—no fluff or redundancy.

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

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

Given the existence of an output schema, the description adequately covers the tool's purpose and return fields. Combined with rich annotations, it is nearly complete. Minor improvement could be mentioning if weapons are sorted or if there is pagination.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description's reference to 'by type' adds no new meaning beyond the schema's 'type' property description. As schema does the heavy lifting, 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 verb 'browse', the resource 'Monster Hunter World weapons', and the purpose: filtering by type and returning damage, elements, and rarity. It effectively distinguishes this tool from siblings like 'get_armor' or 'get_monsters'.

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

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

The description implies usage when you want to browse weapons by type, providing examples. However, it lacks explicit guidance on when not to use it or alternatives, such as comparing with other browse tools or search 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds detail on default behavior (only active) and return fields, but does not contradict annotations.

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

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

Two sentences, front-loaded with purpose and usage. No extraneous content. 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 the simplicity (1 optional param, no output schema), description fully covers purpose, usage, parameters, and return fields. No gaps.

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

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

Schema has 1 optional boolean parameter with full description (100% coverage). Description does not add new information about the parameter beyond schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool 'list the caller's active subscriptions' with specific verb and resource. It also lists the returned fields, distinguishing it from sibling tools like subscribe or 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?

Explicit guidance provided: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly indicates when to use vs. when not.

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 rate limit (5 per identifier per day), free usage, and that it doesn't count against tool-call quota. These details go beyond annotations, which only indicate non-readonly and non-idempotent.

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

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

Four sentences, no fluff. Front-loaded with purpose. Every sentence serves a clear informational 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?

For a tool with 3 parameters (2 required), a nested object, and no output schema, the description covers purpose, usage guidelines, constraints, and content instructions. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by elaborating on enum values for 'type' and advising on message content (be specific, 1-2 sentences). This slightly 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?

The description clearly states the tool sends feedback to the Pipeworx team, enumerating specific use cases (bug, feature, data_gap, praise). It is distinct from sibling tools by being the dedicated feedback mechanism.

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 when to use (bug, feature, data_gap, praise) and what not to do (avoid pasting user prompts). While no alternatives are mentioned, the tool is unique in purpose.

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

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

The description discloses key behavioral traits beyond the annotations: self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h depending on window. Annotations already indicate readOnly, idempotent, non-destructive; the description adds valuable context about data source and caching, 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 two paragraphs with no wasted words. The first sentence states the purpose, followed by bullet-point usage guidelines, and ends with caching and privacy details. It is well-structured and front-loaded with the most important information.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It explains what the tool returns (top tools, top packs, total call volume), the data source (CF analytics-engine), privacy (no PII), and caching behavior. No gaps remain for a read-only aggregate 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 a single parameter (window) having an enum and description. The description adds extra meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the semantic understanding beyond what the schema provides, justifying a score above baseline.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It uses a specific verb ('returns') and resource ('top tools, top packs, total call volume'), and it distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on trending data rather than direct queries.

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

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

The description lists three specific use cases for the tool (discovering hot data sources, confirming canonical tools, seeing alignment). While it doesn't explicitly state when not to use it or name alternatives, the context is clear that this tool is for trending aggregation, not for general queries or research.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral detail: explains the two scanning modes, the semantic anchor (Jaccard similarity ≥0.3) for cross-event matching, partition filter (placeholder drops), and the fill check that prevents trading on non-realizable edges. No contradiction with annotations; the description aligns with and enriches 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 thorough but somewhat long. It is front-loaded with the core purpose, then explains modes. Every sentence adds value, but the paragraph could be broken into clearer sections (e.g., modes, semantic anchor, partition filter, fill check). Still, it's well-organized for a complex tool.

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 covers return fields (opportunities array, partition_check object). It explains all key behaviors: trending_scan scope, event slug format, topic search method, Jaccard threshold, partition filter, fill check integration. Minor missing detail: it doesn't explicitly state what happens when no opportunities are found (likely returns empty array or null).

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds more nuance: explains that no args triggers trending_scan, event mode requires a slug or URL (recommended for specific markets), and topic mode uses a seed question. It also clarifies that event mode performs both monotonicity and partition checks, while topic mode does cross-event scanning. This goes well 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools by specifying the method (monotonicity, partition-sum) and modes (trending_scan, event, topic), making its purpose unique and unambiguous.

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

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

The description explicitly explains when to use each mode: no args for trending_scan, event for a specific market, topic for cross-event scanning. It gives concrete examples of query formats. However, it could be more explicit about when not to use this tool (e.g., if only simple edges are needed instead of full arbitrage detection).

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

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

Disclosures caching behavior (KV-level, 1h), Kelly caps, 24h move warning, and diagnostics for empty segments. Annotations already indicate read-only, idempotent, open-world; description adds significant behavioral context beyond annotations.

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

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

Very long and dense with technical model details (lognormal, GDELT, Kelly formulas) that may be excessive for an AI agent. Well-structured with section labels but could be trimmed without losing essential guidance.

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

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

Comprehensive given 9 parameters, no output schema, and complex segments. Explains response top-level structure, diagnostics for segment emptiness, and all filters. Equally complete for an agent to understand usage and output.

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

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

Schema covers all 9 parameters with descriptions. Main description adds conceptual context (e.g., TRADEABLE-EDGE KNOBS) that enhances understanding beyond schema, supporting the agent's parameter selection.

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

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

Description clearly states the tool scans Polymarket markets for edges where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from potential siblings like `polymarket_arbitrage` by detailing its three response segments.

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 context on when to use (discovering opportunities without paging) and explains the knobs (min_liquidity, max_spread_pp) for tradeability filtering. Lacks explicit comparison with sibling tools but implies usage through segment descriptions.

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

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already indicate safe, idempotent behavior. The description adds valuable behavioral details: limits on history depth (60-day TTL, snapshot start), that decay is from daily closes not intraday, and snapshot gaps due to cache misses. 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 moderately long but well-structured: purpose, then parameter details, response format (tracked[], expired[], snapshot_dates[]), and limits. Every sentence adds value. Slightly wordy in the response explanation but 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 thoroughly explains the response structure with arrays and fields (tracked[], expired[], snapshot_dates[], their subfields, and meanings). It also covers parameter defaults, ranges, and behavioral limits. All essential context is provided for an agent to understand and 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?

Input schema covers both parameters with descriptions (100% coverage). The description adds extra context: default values (days=14, window='1wk'), range for days (max 30), and explanation of window families ('24hr | 1wk | 1mo'), enhancing the schema's 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 purpose: providing edge persistence and decay telemetry from daily snapshots. It uses specific verbs ('answers how long has this edge existed and is it shrinking?') and distinguishes from the sibling tool 'polymarket_edges' by focusing on time-series and decay rather than current edges.

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

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

The description gives clear context on when to use this tool—to assess edge persistence and decay vs. just current edges. It implies the decision tree ('a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when not to use it or list alternatives beyond the sibling 'polymarket_edges'.

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

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

The description extensively discloses behavioral traits beyond annotations: requires one of 'market' or 'event', explains walk-the-ladder mechanics for single-market, details basket-mode return structure (theoretical sum vs realizable sum, capture ratio, thin legs, forced directional risk), and warns about partial fills converting arb into unhedged positions. No contradiction with annotations.

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET, REQUIRES) and front-loads the purpose. Every sentence provides value, but the length is justified due to the tool's complexity. Slight deduction for density, but overall effective.

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

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

Given the tool's complexity (two modes, many output fields) and no output schema, the description thoroughly covers return values for both modes: lists top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. Missing no critical 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%, so baseline is 3. The description adds significant meaning: explains how 'side' default changes in basket mode (auto from partition sum), clarifies 'size_usd' as settlement notional with shares-per-leg semantics in basket mode. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by explaining when this check is necessary.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills causing directional risk), making it clear when to use this tool instead of alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: explaining compatibility_warning fields, temporal alignment, skipped count types, and rareness of real spreads. 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 relatively long but well-structured with clear sections (two modes, response, safety fields). It front-loads the core purpose. Some redundancy could be trimmed, but overall efficient for the complexity.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields, temporal alignment). All three parameters are documented. The tool's behavior is completely described, enabling correct agent 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 coverage is 100%, baseline 3. The description adds meaningful context by explaining the two modes, listing the 10 macro shortcuts for 'topic', and clarifying that explicit parameters override the mapped side. This adds value beyond the schema's property 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 computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes from siblings like polymarket_arbitrage by specifying cross-venue vs within-venue. The verb 'spread' and resource 'Cross-venue spread' is specific.

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

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

Explicitly describes two modes (topic vs explicit parameters) and when to use each. It warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. Provides clear guidance on when spreads are meaningless (temporal misalignment, incompatible bet shapes). Implicitly tells when not to use (e.g., for within-venue arb, use sibling tool).

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping and listing behavior, enhancing transparency 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, front-loaded with main action, no wasted words. Each sentence adds value: action, usage examples, pairing advice.

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 retrieval and listing, explains scoping, pairs with siblings. Adequate given no output schema and simple parameter.

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

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

Schema has 100% coverage with description for key. Description adds real-world examples and the omit-to-list-all behavior, which goes slightly 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 retrieves a saved value by key or lists all keys, with specific examples (ticker, address, notes) and distinguishes from siblings like remember and forget.

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

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

Explicitly states when to use (retrieve context), when to omit key (list all), and mentions scoping to identifier, plus pairing with remember/forget.

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, and destructiveHint=false. The description adds transparency by detailing the response fields (source, citation_uri, payload) and clarifying the mark_read behavior, enhancing the agent's understanding beyond annotations.

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

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

The description is concise, with three sentences that front-load 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?

Given the absence of an output schema, the description sufficiently explains what the tool returns and how filtering and marking read work. It could mention pagination or default ordering, but the limit parameter addresses this.

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

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

With 100% schema description coverage, the baseline is 3. The description adds context by providing an example 'sec_8k' for the type parameter and mentioning ISO timestamp for since, but this doesn't significantly improve 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 'Pull fired events from your subscription feed' and specifies the tool's purpose: returning recent alerts with source, citation_uri, and payload. It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on alerts retrieval.

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 guidance on using mark_read to control alert visibility and mentions an alternative access method (GET endpoint). While it doesn't explicitly exclude other tools, the context makes the usage 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 set readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: the fan-out logic, GDELT→GNews fallback on rate-limit/5xx, USPTO soft-fail until reactivated, and the return structure (changes grouped by source, total_changes, 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 approximately 100 words, tightly packed with high-value information. It starts with concrete user queries, explains the parallel fan-out behavior, describes parameter options, and ends with a sibling distinction. Every sentence adds utility; no repetition of schema fields.

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 3 required parameters, no output schema, and medium complexity, the description covers core behavior well: sources, fallback, parameter formats, return structure. It lacks explicit error handling details beyond USPTO soft-fail, but overall is sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, with each parameter having a description. The description goes further: it explains the since format (ISO date or relative shorthand with examples), clarifies value accepts ticker or zero-padded CIK, and notes that the type enum only supports 'company' today. This adds practical guidance 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 opens with concrete query examples ('What's new with X') and states the tool provides a change feed for a company in a specified window via one parallel call. It lists the three source fan-outs (SEC EDGAR, GDELT/GNews, USPTO) and explicitly differentiates from the sibling tool 'entity_profile' by contrasting the static profile 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?

The description gives explicit when-to-use examples (queries about recent changes) and a clear when-not-to-use directive: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also advises typical monitoring shorthand ('30d' or '1m') for the since parameter.

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

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

Discloses scoping by identifier, persistence difference for authenticated vs anonymous users (24-hour expiry), and idempotent behavior via 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?

Four sentences, front-loaded with purpose, no filler. Each sentence adds essential context.

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 write tool with no output schema, the description covers purpose, usage guidance, storage behavior, scoping, and lifetime. Complete 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 clear descriptions. The description adds examples of what to store but does not add new parameter-level information beyond the schema.

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

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

Description clearly states verb 'save' and resource 'data' with examples. Distinguishes from siblings 'recall' and 'forget' by explicitly pairing with them.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' and provides concrete examples. Mentions alternatives and complementary 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?

Description aligns with annotations (read-only, idempotent) and adds important behavioral details: internal cascading through several endpoints, and specific return fields for each entity type (e.g., ticker+CIK+company_name for company). 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?

Every sentence is informative. Starts with query examples to set context, then a usage directive, then structured details per entity type. No fluff or 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 the two parameters and lack of output schema, the description compensates by explaining what each entity type returns (fields and citation URIs). It is complete for an agent to understand inputs, outputs, and behavior.

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

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

Schema covers both parameters with descriptions, but the description adds extra clarity for the 'value' parameter (lists examples for each type) and explains the enum for 'type'. Adds value beyond the schema.

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

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

The description uses specific verbs and resources ('resolve a user-spoken NAME to the canonical/official identifier'), provides clear examples for both entity types, and distinguishes itself from sibling tools by focusing on resolution of names to IDs.

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 FIRST whenever you have a name but need an ID' and that it replaces multiple manual lookups. It does not explicitly state when not to use it, but the context and sibling tool names provide sufficient differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with metrics, plus a use case example.

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 short (two sentences plus a usage phrase), front-loaded with the main action, and every sentence adds value. No redundancy or unnecessary words.

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

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

Given full schema coverage and annotations, the description covers the tool's operation, output, and use case. It could mention the entity count constraint (2-8) but that is already in the schema. Overall adequate for an AI 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 coverage is 100%, so baseline is 3. The description adds that the first entity is treated as the 'subject' for narrative, which is not in the schema. It also reinforces the purpose of context. This extra information improves parameter understanding.

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

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

The description clearly states the tool's purpose: to compare AI visibility across multiple entities side-by-side, using ai_visibility_check to probe and rank. It distinguishes itself from siblings by focusing on multi-entity comparison and ranking.

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

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

The description provides clear usage context (competitive AI-marketing audits) and an example question, but does not explicitly mention when not to use or list alternative sibling tools. The guidance is implied rather than stated.

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 significant behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia may take 5-30s on first measurement, and sources_failed will list timeout failures. It also details the return structure, which is not in annotations.

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

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

The description is informative and front-loaded with the main purpose. Each sentence adds value, though it is slightly verbose. Could be trimmed slightly without losing meaning.

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

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

Given no output schema, the description fully explains the return values: summary fields, per-advisory detail, links, alternative versions, and error handling. It covers all essential aspects of the tool's behavior and output.

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

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

Schema coverage is 100% and the schema already describes both parameters well. The description adds minimal extra meaning beyond purpose context, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for whether to add an npm package, aggregating data from deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency' and distinguishes from sibling tools by focusing on npm packages.

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: for questions about safety, popularity, size, or cost of adding a package. It also provides an exclusion for other ecosystems (PyPI, Maven, etc.) and directs to deps.dev:version directly. This is clear 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 (readOnlyHint, etc.), the description reveals truncation at 200K chars, embedding model (BGE-base-en), cosine similarity over 500-char windows, return of top-N passages with offsets and scores. 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?

Description is a single dense paragraph that front-loads purpose and usage. It is concise but could be broken into bullet points for better readability. 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?

No output schema, but the description explains return values (passages with offsets and scores) and edge cases (truncation). It also mentions pairing with a specific sibling tool, making it complete for its purpose.

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 descriptions are adequate. The description adds value by explaining the query as natural-language with examples, and mentioning truncation for text. Slightly redundant but still helpful.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and specifying when to use (record too big for prompt).

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

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

Explicit usage guidance: 'Use when the record is too big to cram into the prompt' and 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This tells when to use and suggests an alternative approach.

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 idempotentHint=true, destructiveHint=false. Description adds non-obvious behaviors: OAuth requirement, per-type parameter, delivery limits (10/day SMS), webhook secret returned once, and auto-disable after 10 failures. No contradictions.

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

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

The description is somewhat long but efficiently packed with crucial details. Front-loaded with purpose, then organized by type and delivery. Every sentence adds value; minor redundancy possible but overall good.

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

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

Given the complexity (multiple types, nested delivery object, auth, rate limits, no output schema), the description covers all essential aspects: return value, prerequisites, type-specifics, and edge cases (webhook secret, auto-disable).

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 rich context: examples for each type (e.g., sec_8k items codes), delivery object explanation (webhook HMAC signing), and constraints (phone must be verified). Greatly enhances 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 creates a proactive monitoring subscription and returns the subscription id. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and live-data streams.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with parameters, and delivery channels with limitations. No explicit when-not-to-use, but the detail is sufficient for an agent to decide.

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

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

Annotations already declare idempotent, readOnly, non-destructive. The description adds that it returns example questions and can be focused by topic, but does not contradict or add significant behavioral traits beyond purpose. It is transparent about its 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 comprehensive but slightly long. It is well-front-loaded with the purpose and common queries, and structured with parameter usage at the end. Every sentence adds value, but could be tightened slightly without losing clarity.

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

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

The description fully explains what the tool returns (category-bucketed example questions with exact tool usage), when to use it (first time onboarding), and how to use the optional parameter. Without an output schema, this is sufficient for an agent to understand and invoke the tool correctly.

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

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

The schema provides 100% coverage for the only parameter 'topic' with a description of possible values. The description adds value by elaborating on usage (omit for spread, provide topic to focus) and listing sample topics, expanding on the schema's 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 returns category-bucketed example questions with exact tool and argument shapes, distinguishing it as an onboarding entry point. It answers common user intents like 'what can I ask?' and specifies it draws from a live catalog.

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

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

The description explicitly says to use this tool first when unsure what Pipeworx can do, or to learn how to call meta-tools. It also contrasts with other tools by mentioning it provides exact tool usage, giving clear guidance on when to use vs alternatives.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds that ownership is enforced and the row is deactivated not deleted, keeping historical events available. This provides crucial behavioral context for a mutation tool.

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 redundancy. The first sentence states the action and constraint, the second explains the side effect. Efficient and well-structured.

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

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

Given the simplicity (one parameter, no output schema), the description fully covers purpose, usage constraints, and behavioral details. No gaps remain for 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?

The schema covers the parameter 'id' fully (100% coverage). The description adds value by stating 'by id' and linking to subscribe's output, indicating the source of the id. This enhances understanding beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id', specifying the verb and resource. It distinguishes itself from sibling tools like 'subscribe' 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?

It explicitly mentions ownership enforcement and the deactivation behavior (not deletion), guiding when to use and clarifying side effects. Lacks an explicit 'when not to use' but provides sufficient context.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds value by explaining the verdict types, citation format, and the two distinct processing paths (SEC EDGAR vs grounded pipeline). 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 comprehensive and front-loaded with trigger phrases and purpose. It efficiently covers use case, behavior, and output. Slightly long but every sentence adds value; 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 only 2 parameters, 100% schema coverage, and no output schema, the description fully explains the tool's behavior, output format (verdict, actual value, reasoning), and processing paths. It is complete for the tool's complexity.

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

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

100% schema coverage already describes both parameters. The description adds extra context: tolerance_pct overrides default from wording, capped at 5, and is useful for hallucination detection. This exceeds what schema provides.

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

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

The description clearly states the tool's purpose: verify natural-language claims against authoritative sources. It provides specific examples of claim types and natural-language triggers. It distinguishes itself from sibling tools by describing its specialized dual-path processing for company financials versus other claims.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Details the two processing paths but lacks explicit 'when not to use' or alternatives, though the context is clear.

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