Coordinates

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds context on model selection, API key handling (BYO key, direct payment), and return structure. No contradictions. The description enhances transparency beyond annotations.

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

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

Description is compact (4 sentences) with front-loaded main purpose. Each sentence adds essential information: action, model options, return format, use cases. 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?

For a tool with no output schema, description adequately covers return values (per-model {score, confidence, signals, raw_response} + combined view). It also explains the default model and optional Anthropic integration. Missing details like pagination or error handling, but overall sufficient for a probing tool with safe annotations.

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

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

Schema coverage is 100%, so parameters are already documented. Description adds value by explaining default model behavior, how _apiKey is used (passed straight through), and how context helps disambiguate. This provides semantic understanding beyond the schema.

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

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

Description clearly states the tool probes LLMs and scores visibility for entities. It specifies verb ('probe'), resource ('LLMs'), and outcome ('score visibility 0-100'). The output format is described, distinguishing it from sibling tools like deep_research or scan_competitor_ai_presence.

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

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

Description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to use the optional Anthropic model. However, it does not mention when not to use or compare to alternatives, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral context beyond annotations: it returns 'structured answer with stable pipeworx:// citation URIs', routes to specific verified sources, and notes it 'works on every tier, one fast call'. No contradictions with annotations. Some missing details about rate limits or exact response format, but the annotations already cover safety profile.

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

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

The description is fairly long but front-loaded with the most critical guidance ('PREFER OVER WEB SEARCH') and provides structured sections with examples and sibling differentiation. While some repetition could be trimmed (e.g., multiple mentions of citations), the length is justified given the tool's complexity and the need to explicitly guide selection 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 (5564 tools, 1462 sources) and no output schema, the description provides good high-level completeness: it covers when to use, what it returns (structured answer with citations), and how it differs from siblings. However, it does not describe the exact output format or pagination behavior, which would help an agent interpret results reliably. Still, it is sufficient for agent selection and basic 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% with all parameters having descriptions (mostly aliases for question). The description does not add significant meaning beyond what the schema provides; it merely restates that the tool accepts natural language questions. The examples in the schema are useful but not part of the description itself. Baseline 3 is appropriate since schema already documents the parameter well.

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

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

The description clearly states the tool routes questions to thousands of sources and returns structured answers with citations. It uses specific verbs like 'routes', 'fills arguments', 'returns', and explicitly distinguishes from siblings by naming ask_pipeworx_grounded and deep_research. Concrete examples (e.g., 'current US unemployment rate', 'Apple's latest 10-K') reinforce the purpose.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for a wide range of factual data, and 'START HERE for most questions'. It also gives when-not-to-use by directing to alternatives: 'Step up only when needed' for ask_pipeworx_grounded (confidence + verbatim evidence) and deep_research (broad multi-part questions). This clearly differentiates usage contexts.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral context: it is a full working router that currently matches ask_pipeworx exactly, with a fallback to nothing (i.e., no fallback to a safe mode), and it indicates the experimental nature. The description does not contradict annotations and complements them well. It could further detail what happens when a candidate is active (e.g., potential for differences), but the current state is well explained.

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 focused sentences. The first sentence defines the tool's nature and scope, the second explains the current state, and the third gives usage guidance. Every sentence is informative and non-redundant. It is front-loaded with the most critical info (beta version of existing tool) and avoids unnecessary detail.

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 (router for 5,564 tools), no output schema, but thorough annotations (readOnlyHint, idempotentHint, etc.), the description is complete. It explains the experimental edge purpose, current state (no active candidate), and how to use it (same as ask_pipeworx). No gaps remain for selecting and invoking this 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% and all 6 parameters are thoroughly documented as aliases for 'question'. The description adds no additional parameter semantics beyond what the schema already provides, but given the high coverage, the baseline is 3. The description earns a 4 because it provides crucial context about the parameter being a natural language query that routes to thousands of tools, which aids interpretation beyond just the aliases.

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

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

The description clearly states it is a beta version of ask_pipeworx, an identical universal router with 5,564 tools, same arguments, and same response shape. It distinguishes itself from the sibling ask_pipeworx by highlighting candidate routing improvements that are tested live, and it explicitly notes when no candidate is active, making its current state transparent.

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 wanting the newest routing, and mentions that results are compared against the stable router to decide merges. It does not explicitly exclude any scenarios or mention when not to use it, but the context of 'experimental edge' implies it is for testing new routing, which is clear enough.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which the description does not contradict. The description adds valuable behavioral context: costs one extra LLM call, returns explicit refusal reasons when data doesn't answer, and the extraction mechanism. However, it does not mention rate limits or any authorization requirements, which would be useful but are not critical to contradfict 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 dense with useful information in a compact space: purpose, mechanism, trade-off, use cases, response format, and refusal reasons. It could be slightly more structured (e.g., bullet lists) but is efficient for an AI agent. No wasted 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?

The description fully explains the tool's behavior given its complexity—it's a grounded answer tool with explicit refusal modes. With no output schema, the description compensates by detailing the return object structure. The only minor gap is not explaining what happens when multiple tool matches exist or more about the 'picks the right tool' logic, but the context signals suggest simple parameters and no nested objects, so this seems sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the 'question' parameter (and its aliases) is a natural language query and that the tool will fill arguments for other tools internally. This clarifies usage beyond what the schema provides, justifying a 4.

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

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

The description clearly states 'Hallucination-resistant answer mode for high-stakes reads' and contrasts it with the sibling ask_pipeworx, specifying that it extracts answers using only the tool result. It explicitly lists when to use (financial verdicts, legal claims, medical lookups, public statements) and details the structure of success and refusal responses.

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

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

The description explicitly states when to use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when not to use ('prefer ask_pipeworx for casual lookups' due to extra cost). It clearly differentiates from sibling tools by naming the alternative and its trade-off.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral details: fan-out logic per classifier, response shapes, resolver contract, parent event extraction, news fields with fallback info, safety on low-confidence matches, closed market handling, liquidity warnings, and cancellation rule parsing. 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 lengthy but well-structured with examples, bullet points, and sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). The first sentence immediately states purpose. Some redundancy could be trimmed, but the complexity justifies the length.

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

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

Despite no output schema, the description thoroughly explains return values, response shapes, and edge cases (low confidence, closed markets, wide spreads, cancellation rules). Covers all aspects a user needs for effective tool usage.

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

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

Schema coverage 100%; description adds context beyond schema: explains input resolution (slug, URL, text), depth options (quick vs thorough), and include_raw purpose and trade-offs. Enhances understanding of all three 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and output components, distinguishing it from sibling tools like polymarket_edges or validate_claim.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also warns to inspect resolver confidence before trusting analysis, and mentions the tool is not for edge tracking across markets (handled by 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 false. The description adds the behavioral detail that the tool returns SW/NE corners of the bounding box. 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?

Single sentence that front-loads the purpose and includes key parameter details. No redundant words, highly efficient.

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

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

Annotations are comprehensive, and the tool's output is implied by 'SW/NE corners'. The description is sufficient for a simple geometric computation tool, though it could explicitly state the return format.

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 4 parameters with 50% description coverage (unit and radius have descriptions). The description adds context by clarifying the output format (SW/NE corners) and the default unit, complementing the schema. However, it does not add new semantic constraints beyond what the schema provides.

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

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

Description clearly states the tool computes a bounding box (SW/NE corners) from a center point and radius. It distinguishes from sibling spatial tools like centroid or midpoint by specifying the output geometry and parameters.

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

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

Description provides the default unit (km) and alternative (mi), but no explicit guidance on when to use bounding_box vs other sibling tools. Usage context is implied through the description of the tool's function, but no exclusions or alternative recommendations are given.

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 matches annotations (readOnly, idempotent). No additional behavioral details beyond what annotations provide, but no contradiction.

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

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

Two sentences, no wasted words. Purpose and parameter clearly stated in minimal space.

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 tool is simple. Description could mention return format (single {lat,lon}) for completeness. Adequate but not thorough.

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

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

Schema already fully describes 'points' parameter (100% coverage). Description only repeats schema info, adding no new 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 computes the average (spherical) center of lat/lon points. It distinguishes from sibling 'midpoint' by specifying spherical calculation.

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

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

No guidance on when to use this tool vs alternatives like 'midpoint'. Lacks explicit when-to-use or when-not-to-use 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds critical context: for type='company' it pulls latest 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly; for type='drug' it pulls FAERS adverse-event counts, FDA approval counts, and active trial counts. It also explains sorting by primary metric and return of citation URIs. No contradiction.

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

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

The description is a single paragraph that effectively front-loads examples and purpose. Every sentence adds value, but the structure could be slightly improved with bullet points for readability. Still, it is concise for the complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources), the description covers main behaviors comprehensively: data sources, sorting, return of paired data and citation URIs. It compensates for the lack of an output schema by explaining the result characteristics.

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

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

Input schema has 2 parameters (type, values) with 100% schema coverage. The description adds meaning beyond the enum and array descriptions: explains what data is pulled for each type (e.g., revenue, net income, cash, debt for company; FAERS counts, FDA approvals, trials for drug) and specifies value formats (tickers/CIKs for company, drug names).

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 comparison of 2-5 companies or drugs, using action verbs like 'compare', 'rank', and 'head to head'. It distinguishes itself from sibling tools such as entity_profile (single entity) and deep_research (extensive research).

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

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

The description explicitly instructs to prefer this tool over sequential single-pack lookups when comparing entities, and provides examples like 'which is bigger', 'rank these companies'. It sets clear expectations for when 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 include readOnlyHint and openWorldHint, so the description adds substantial context beyond them: account requirements, parallel execution of 5,564 tools, gap recovery behavior, contradiction scanning, hop fields, citation resolvability, excerpting semantics, and expected latency ranges. This comprehensive disclosure far exceeds what annotations alone provide.

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

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

The description is comprehensive but suffers from density and structural issues. Critical constraints (account requirement, breaking news limitation) are front-loaded, but the middle section becomes a wall of technical details without clear sectioning or hierarchy. Every sentence adds value, but readability could be improved with bullet points or whitespace.

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 high complexity (two parameters, no output schema, multiple behavioral nuances), the description covers account requirements, alternatives, use cases, process details, latency, and return properties. The only gap is that it doesn't explicitly state the return type (e.g., 'object with findings, gaps, contradictions'), but the findings packet description is adequate. A 4 reflects thoroughness with minor improvement possible.

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 (question and depth). The description adds meaningful detail beyond the schema: depth enum values are explained with process differences (gap-recovery hop, contradictions scan, iterative hop) and the question parameter's scope is clarified. While the schema does a good job, the description enhances understanding, so a 4 is appropriate.

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

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

The description clearly states the tool performs 'grounded multi-source research' across '1462 STRUCTURED data sources' in a single call, with explicit comparison to siblings like ask_pipeworx and ask_pipeworx_grounded, making its purpose highly specific and distinguishable.

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

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

The description provides explicit when-to-use guidance (broad/multi-part structured data questions), when-not-to-use ('BREAKING or colloquial CURRENT-NEWS...prefer ask_pipeworx'), and names alternative tools (ask_pipeworx) with reasoning, satisfying the highest usage guideline standards.

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 value by noting that results include full input schemas with curated examples and are ready to call directly, which is not covered by 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 somewhat lengthy but every sentence adds value. It front-loads the core purpose and usage guidance. Could be slightly more concise, but no waste.

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

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

Given no output schema, the description thoroughly explains the return value (top-N tools with names, descriptions, and full schemas). Parameter count is reasonable with aliases correctly handled. Complete and self-sufficient.

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

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

Schema coverage is 100%, but the description enhances parameter understanding by listing accepted aliases for 'query' and providing example queries. It clarifies that 'limit' defaults to 20 and maxes at 50, adding context 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: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from siblings, none of which are discovery tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear guidance on when to use versus alternative approaches.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: fans out across multiple sources, returns specific fields (cik, recent_filings with URIs, fundamentals, patents, news, LEI), notes patent sunset and soft-fail behavior, and clarifies input limitations. 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 dense and front-loaded with trigger phrases, then explains behavior and returns in a structured but prose format. It is appropriately sized with no redundant sentences, though a bulleted list might improve scanability slightly.

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 thoroughly explains the return value structure (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and behavioral nuances (parallel call, patent sunset, name limitation). It feels complete for an agent to understand what the tool does and what it returns.

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

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

Schema description coverage is 100%, so the description adds no extra meaning beyond what's already in the schema for parameters 'type' and 'value'. The description reiterates that value accepts ticker or zero-padded CIK and that names are not supported, matching the schema exactly. 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 generates a full cross-source profile of a US public company in one parallel call. It provides example trigger phrases ('Tell me about X') and distinguishes it from sibling tools like resolve_entity and compare_entities by emphasizing its holistic nature.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' It also specifies when not to use: if only a name is available, use resolve_entity first, providing clear guidance on alternatives.

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

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

Annotations already indicate destructiveHint=true. Description adds context about clearing sensitive data and use cases, which is valuable 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?

Two sentences, front-loaded with purpose, no wasted words.

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

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

For a simple destructive tool with one parameter and no output schema, description fully covers usage and 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 description adds no additional meaning to the single parameter 'key' beyond what the schema provides.

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

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

Description clearly states 'Delete a previously stored memory by key.' with a specific verb and resource, and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also mentions pairing with remember and recall, providing clear 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 provide readOnly, idempotent, and non-destructive hints. The description adds the process of fetching the page and extracting content, which complements annotations. No contradictions, but lacks details on error handling or rate 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?

The description is concise with three core sentences followed by use cases. Every sentence adds value, and the structure front-loads key information efficiently.

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 no output schema, the description explains the output format and location. It covers the generation process and use cases adequately, though it omits potential edge cases like invalid URLs.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description does not add significant meaning beyond what the schema provides, maintaining 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 it generates a production-ready llms.txt file from a URL, listing the steps and output format. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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 provides explicit use cases (client site indexing, personal project, competitor audit), giving clear context for when to use. However, it does not mention when not to use or explicitly exclude alternatives among siblings, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds the return fields and clarifies that it lists active subscriptions (with optional inactive via parameter). This provides useful behavioral context beyond the annotations.

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

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

Two efficient sentences: the first describes the purpose and return fields, the second gives usage advice. 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?

The description fully covers the tool's function for a simple list operation: it names the return fields and mentions the optional parameter. No output schema exists, but the description compensates by listing the fields. The single parameter is well-documented in the 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 description coverage is 100% for the single parameter (include_inactive). The description does not add additional meaning beyond what the schema already provides. 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 'List the caller's active subscriptions' with a specific verb and resource, and lists the returned fields (id, type, params, created_at, last_fired_at, fire_count). This distinguishes it from sibling tools like subscribe and unsubscribe which have different actions.

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 this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on when to use versus alternatives like subscribe or unsubscribe.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds 'great-circle' method, but does not disclose edge cases or precision 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?

Single sentence, no unnecessary words. Efficiently conveys the tool's 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?

The description is adequate for a simple tool with annotations and examples, but it lacks any mention of return value or error conditions. Since no output schema exists, this is a gap.

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 0%, and the description does not explain parameter meanings. While parameter names and examples are self-explanatory, there is no mention of valid ranges or units, leaving gaps.

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 the geographic great-circle midpoint between two latitude/longitude points. This distinguishes it from sibling tools like centroid (multiple points) and bounding_box (bounds).

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

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

No explicit guidance on when to use this tool versus alternatives. The name and description imply it's for exactly two points, but there's no comparison to centroid or other spatial 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 provide little (all false), so the description carries the burden. It discloses the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), rate limiting ('Rate-limited to 5 per identifier per day'), and cost ('Free; doesn't count against your tool-call quota'). It also mentions the team's daily digest reading and roadmap impact, giving a clear behavioral model.

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

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

The description is dense but every sentence provides a distinct, practical fact: use cases, exclusions, token workflow, rate limits, and quota. It is front-loaded with the core purpose and does not repeat schema content. Length is appropriate for the complexity of the 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?

Despite no output schema, the description explains what happens (token returned, status read) and gives operational context (daily digests, rate limit, quota). It covers prerequisites (account vs. no account) and content constraints, making it complete for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with detailed descriptions for each parameter, giving a baseline of 3. The description adds value by reinforcing the claim_token usage pattern and by advising message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which the schema only partially implies. This extra guidance justifies a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the action (sending feedback) and the target (Pipeworx team). It enumerates specific feedback types (bug, feature/data_gap, praise), distinguishing it from sibling tools like ask_pipeworx which are for inquiries. The verb 'tell' and resource 'Pipeworx team' make the purpose unambiguous.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog...' It also provides a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage guidance with alternatives and exclusions.

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

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

Descriptions adds details beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs about data source, privacy, caching behavior. Annotations already cover safety, but description enriches 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?

Every sentence adds value. Front-loaded with core output, then use cases, then technical details. No fluff.

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

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

Despite no output schema, description explains returned fields (top tools, top packs, total call volume) and covers caching, data source, privacy. Complete for a simple read-only tool.

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

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

Schema coverage is 100% and enum values are listed. Description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose appropriately.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume' over a time window, using specific verbs like 'Returns' and 'Discovering'. It distinguishes from sibling 'discover_tools' by focusing on trending/call volume rather than static discovery.

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

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

Three explicit use cases are listed, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or compare to alternatives like 'discover_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 and destructiveHint=false, so the description's mention of 'Test whether' aligns. However, it does not elaborate on return values or edge cases, but the annotations suffice for basic 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?

A single, front-loaded sentence with no wasted words. Every part contributes to understanding the tool's purpose and parameter format.

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 test tool with three parameters and no output schema, the description covers the core functionality well. Lacks mention of return type (likely boolean), but examples aid understanding. Nearly complete.

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

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

Schema description coverage is 33% (only bbox described). The description adds meaning for bbox (format: minLat,minLon,maxLat,maxLon). Lat and lon lack additional description, but examples in schema provide context. Partial compensation for low coverage.

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

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

The description clearly states the tool's action ('Test whether'), the resource (lat/lon point and bounding box), and the bounding box format. It is distinct from siblings like 'bounding_box' and 'centroid'.

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

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

No guidance on when to use this tool versus alternatives. For example, it doesn't explain how it differs from 'bounding_box' or when a point-in-bbox test is appropriate.

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

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

Annotations declare read-only and non-destructive. The description adds extensive behavioral context: internal checks (monotonicity, partition sum), semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder slugs), fill check (theoretical vs realizable edge), and response structure. 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 verbose but well-structured: starts with a summary, then details modes and internal logic. It front-loads key information but includes extraneous details (SEMANTIC ANCHOR, PARTITION FILTER) that could be shortened.

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 complex tool with two modes, multiple internal algorithms, and no output schema, the description is extremely comprehensive. It explains response fields, fill check logic, trade recommendations, and even references a sibling tool for custom sizing.

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. The tool description adds extra meaning: clarifies that event expects a slug or full URL, topic is a seed question for cross-event search, and explains how each parameter affects the analysis.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk by explaining unique arbitrage detection logic.

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

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

Explicit guidance is given: no args for trending scan, event for specific market, topic for cross-event scan. Examples of event slugs and topic questions are provided. It also recommends an alternative tool for custom sizing ('use polymarket_fill_risk').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's safe. The description adds rich behavioral context: caching (1h at KV level keyed on all knobs), response structure with diagnostics on why segments might be empty, and detailed derivation of edge metrics (e.g., Kelly fractions, edge_pp_net after slippage). 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 very long but well-organized with clear sections for model families, output fields, and parameter instructions. It front-loads the core purpose. However, some details (e.g., full explanation of each model) could be trimmed or moved to a more structured format for easier consumption by agents.

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 (by_segment segments, fed_candidates/fed_note, _diagnostics) and the fields carried by each opportunity (edge_pp_net, kelly_fraction, liquidity, etc.). Parameters are all described with practical guidance. The caching behavior is noted. The tool is self-contained for an agent to use correctly.

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

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

Schema coverage is 100%, baseline 3. The description goes far beyond schema descriptions: it explains how each parameter acts as a 'tradeable-edge knob', provides example values (e.g., 'Set to 5000 to drop thin-book opportunities'), and clarifies interactions (e.g., min_partition_leg_kelly vs. min_kelly for partition arbs). This significantly aids correct invocation.

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

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

The description clearly states that the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today' discovery. It lists three distinct model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and explains their characteristics, making the tool's function precise and distinct from siblings like polymarket_arbitrage.

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 context for when to use the tool ('what should I bet on today') and details parameter knobs for filtering (tradeable-edge filters, min_kelly, etc.). However, it does not explicitly state when NOT to use this tool compared to alternatives like polymarket_arbitrage or polymarket_fill_risk, though the uniqueness of the approach is implied.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: snapshots written on cache-miss, gaps mean no scan, decay from daily closes, and response details (tracked, expired, snapshot_dates). 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 structured: overall purpose, args, response format, and limits. It is front-loaded with the core question. Every sentence delivers new information, but could be slightly more concise by merging some repetitive points. Overall efficient.

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

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

Despite no output schema, the description fully explains the response objects: tracked[], expired[], snapshot_dates[], including fields like trend, decay_pp_per_day, lifespan_days. It also covers limitations and data sources. This is comprehensive for a tool with two simple parameters.

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 adds value by clarifying defaults ('default 14', 'default 1wk') and constraints ('max 30'), and listing valid window values (24hr, 1wk, 1mo) beyond the schema's vague description. However, the schema already captures core semantics.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?' The verb 'track' and resource 'edges over time' are well-defined, distinguishing it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implicitly advises when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades', indicating historical context is crucial. It also mentions limits like 60-day TTL and snapshot gaps. However, it lacks explicit when-not-to-use or direct reference to alternatives, but sibling differentiation is handled elsewhere.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral details like walking the order book ladder, returning specific fields, and highlighting thin-leg risks, completely consistent with annotations.

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

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

The description is long but well-structured with clear sections for each mode and important warnings. It front-loads the core purpose, though minor trimming could improve conciseness.

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

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

No output schema exists, but the description comprehensively lists all return fields for both modes, explains the verdict categories, and covers edge cases like forced directional risk, making it self-contained.

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

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

Schema coverage is 100%, but the description adds usage nuances like auto-detection of side in basket mode, interpretation of size_usd, and clamps ranges, enhancing semantic 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 checks realizable-vs-theoretical edge against live CLOB depth. It distinguishes two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) for context.

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

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

The description explicitly tells when to use this tool (before acting on arbitrage signals or edge trades above ~$500) and provides warnings about partial fills and unhedged positions, guiding correct usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context beyond these, detailing safety fields like compatibility_warning, temporal_alignment, and skipped counters, and explains that real spreads are rarer than suggested.

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 somewhat verbose (multiple paragraphs). However, it is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS), making it easy to parse despite length. Minor trim could improve conciseness.

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

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

Given no output schema, the description thoroughly covers return format and safety fields, explains edge cases (incompatible shapes, temporal misalignment, skipped comparisons), and provides enough context for an AI to understand the tool's behavior and limitations.

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

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

Input schema has 100% description coverage. The description adds detailed semantics: how topic interacts with explicit tickers, examples, and explains the response structure including spread fields and safety fields, providing value beyond schema alone.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, and distinguishes two modes (topic shortcuts vs explicit pairings), which differentiates it from sibling tools like polymarket_arbitrage.

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 (comparing prices for equivalent outcomes) and when not (when compatibility_warning fires due to non-equivalent bet shapes or unrelated events). It provides clear guidance on pre-mapped topics vs explicit pairs and warns that pre-mapped does not mean tradeable.

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 scoping detail (identifier-based) and pairing guidance, providing useful 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?

Two sentences are efficient, front-loaded with action, and contain no redundant information. 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?

With a single optional parameter and rich annotations, the description covers all necessary behavioral context: what it does, when to use, scoping, and tool relationships.

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

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

Schema covers 100% of parameters. Description adds the critical behavior of omitting key to list all keys, which is not in the schema description, enhancing 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 retrieves a value by key or lists all keys, distinguishing it from siblings remember and forget. Specific verb and resource make purpose unambiguous.

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

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

Explicitly states when to use (look up context stored earlier) and names complementary tools (remember, forget). Does not explicitly exclude scenarios, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. Description adds side effects of mark_read flag and explains return format (source, citation_uri, payload). 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?

Three sentences, each valuable. Front-loaded with main action. 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?

Describes return fields, filtering, and side effects. Mentions polling safety and alternative access. Missing pagination details but sufficient for a read 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%, description adds examples (e.g., 'sec_8k'), explains mark_read effect, and clarifies since as ISO timestamp. Adds meaning beyond schema.

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

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

Clearly states it pulls fired events from subscription feed, returns alerts with source, citation_uri, and payload. Distinguishes from siblings by mentioning polling and alternative GET endpoint.

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

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

Provides explicit guidance on filtering by type and/or since, setting mark_read, and notes polling works fine. Gives alternative access method. Lacks explicit when-not-to-use instructions but is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals that the tool fans out to three data sources (SEC, GDELT/GNews, USPTO) with fallback logic (GDELT preferred, GNews when rate-limited) and a soft-fail condition (USPTO). This adds valuable context about internal behavior not captured by 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 coherent paragraph that front-loads example queries, then explains data sources and fallbacks, parameter details, and ends with a sibling comparison. Each sentence adds value, but the density could be slightly improved with bullet points or clearer segmentation.

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

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

For a read tool with three parameters and no output schema, the description covers source behavior, fallback logic, soft-fail conditions, and parameter formats. It addresses temporal boundaries (window) and provides a comparison with a sibling. Minor gaps: no mention of return structure details (e.g., 'pipeworx:// citation URIs' is listed but not explained), but overall sufficient.

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

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

Schema coverage is 100%, but the description enhances parameter understanding by providing practical examples for 'since' (ISO date, relative shorthand like '30d', '1y') and clarifying that 'value' accepts either ticker or zero-padded CIK. This reduces ambiguity and adds usage guidance beyond the schema's formal 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 starts with concrete example queries ('What's new with X', 'updates on Acme') and states it returns a change feed for a company over a window. It explicitly distinguishes from sibling tool entity_profile ('Use entity_profile instead when you want the static profile'). This provides a specific verb ('return changes') and resource ('company change feed'), with sibling differentiation.

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

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

The description explains when to use this tool ('What's new with X' queries) and when to use the sibling entity_profile ('static profile'). It also notes a temporal concern (USPTO soft-fails after May 2025). However, it does not explicitly state when not to use it or mention alternatives for other query types.

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 idempotent and non-destructive. Description adds value by explaining scope (key-value per identifier) and retention (24h for anonymous, persistent for authenticated users). 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?

Five focused sentences, each adding value. Front-loaded with core action, then expands with usage examples, persistence details, and related tool references. No fluff.

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

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

For a simple write tool with two parameters and no output schema, the description covers action, usage, persistence, and siblings. Minor omission like size limits 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%, baseline 3. Description provides concrete examples of key-value pairs (e.g., 'subject_property', 'target_ticker') that add meaning beyond schema descriptions.

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

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

The description clearly states the tool saves data for reuse, with specific examples (ticker, address, preference). It 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 says 'Use when you discover something worth carrying forward' and gives context about persistence differences based on authentication. No explicit when-not-to-use, but clear enough.

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

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

The description goes far beyond the annotations by explaining graceful degradation (LEI/FIGI enrichment fails but EDGAR still returns), explicit behavior for unresolved identifiers (listed under `unresolved` rather than omitted), and the internal cascade of lookup endpoints. No contradiction with annotations (readOnlyHint, idempotentHint, openWorldHint).

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

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

Although long, the description is extremely well-structured: it opens with example intents to immediately convey purpose, then gives the directive, then explains each type in detail, and closes with failure behavior and efficiency benefits. Every sentence contributes essential information; nothing is redundant or vague.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: for company, it lists CIK, ticker, company_name, LEI with ownership details, FIGI, and the unresolved list; for drug, it lists RxCUI, ingredient, brand, and citation. It also covers edge cases like unavailable enrichment and multi-endpoint behavior, making it complete for a tool of this complexity.

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

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

The schema provides basic descriptions for both parameters, but the description massively enriches them: it details what each `type` returns, what the `value` accepted formats are (ticker, CIK, ISIN, brand/generic), and even explains special cases like ISIN-to-LEI mapping. This adds significant semantic 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: resolving user-spoken names to canonical identifiers. It provides concrete example queries (ticker, CIK, LEI, RxCUI) and specifies supported entity types. It explicitly positions itself as the first step before other tools, distinguishing it from siblings like entity_profile or 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?

The description gives explicit usage direction: 'Use FIRST whenever you have a name but need an ID.' It also details acceptable input formats for different types. However, it does not explicitly mention alternative tools like entity_profile for cases where an ID already exists, so it lacks the 'when-not/alternatives' specifics required for a 5.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it 'probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized' and mentions the return format (score, confidence, signal density). This goes beyond annotations by explaining internal mechanism and output structure. No explanation about potential costs or rate limits for Anthropic API, but sufficient for basic 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?

Three sentences: first defines core action, second explains method and ranking, third gives use case and return summary. No filler words, front-loaded with purpose, and every sentence contributes value. Perfectly sized for quick comprehension.

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

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

Given no output schema, the description adequately covers return values (ranked list with score, confidence, signal density). It also explains the dependency on ai_visibility_check and the optional Anthropic API key. For a tool with multiple entities, optional models and context, the description is complete and covers all necessary 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 meaning beyond schema by noting that the first entity is treated as the 'subject' for narrative, and that the tool 'probes each entity with ai_visibility_check'. This clarifies the ordering and the internal process, which is not available from the schema alone.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', specifying the verb (compare), resource (AI visibility of entities), and scope (multiple, side-by-side). It distinguishes from sibling 'ai_visibility_check' by focusing on comparison vs. single-check, and from 'compare_entities' by specifying AI visibility context.

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

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

The description explains the tool is 'Useful for competitive AI-marketing audits' and provides an example query 'does Claude know about us as well as our competitors?'. It implies single-entity checks should use ai_visibility_check instead. Lacks explicit when-not-to-use or alternative names, 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?

Beyond annotations (readOnlyHint, etc.), the description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, sources_failed will list timeouts, and the rest still returns. No contradiction with annotations.

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

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

The description is a single well-structured paragraph that front-loads purpose, then usage, then return details, then limitations. Every sentence is informative and necessary.

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 compensates by listing return fields (summary block, per-advisory, links, alternatives) and explaining partial failure behavior. It provides a complete understanding for 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%. Description adds value by noting scoped packages are accepted for 'package' and that 'version' defaults to latest when omitted. It also describes the structure of return fields, which is helpful since there is no output schema.

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

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

The description clearly states it's a composite check for npm packages, covering license, advisories, version history, and bundle size. The verb 'scan' and resource 'dependency' are specific, and the tool is differentiated as a one-call composite.

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

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

Explicitly says when to use: 'Use whenever an agent asks 'is X safe / popular / small'' and gives an example. Also explains ecosystem limitations (NPM only in v1) and directs to alternatives for other ecosystems.

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

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

Adds significant behavioral context beyond annotations: embedding model (BGE-base-en), chunking (500-char overlapping windows), character limit (200K chars) with truncation flag, and return format (passages with offsets and scores). 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?

Single paragraph is well-structured, front-loaded with purpose, then usage, then technical details. Every sentence adds unique value with no redundancy.

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

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

Despite no output schema, description thoroughly explains return values (passages with offsets and scores), technical details (embeddings, windowing, truncation), and pairing advice. Complete for a read-only search tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by providing example queries and clarifying that limit is max passages (1-20, default 5), exceeding baseline.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb+resource. Distinguishes from siblings by referencing ask_pipeworx_grounded and explaining use case for large documents.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. Provides clear context and alternative, making it easy 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 indicate a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral details: OAuth requirement, SMS daily cap, webhook auto-disable after 10 failures, and the return of a subscription ID. 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 paragraph that is dense with information but remains readable. It front-loads the core purpose. While it could benefit from structured bullets for readability, it is not excessively long for the complexity of the 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 adequately covers return behavior (subscription ID). It explains all subscription types, required params, delivery channels with examples and limitations. For a subscription creation tool with nested objects, it is thoroughly 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 100% of parameters, but the description enriches every parameter with type-specific formats and examples (e.g., sec_8k items, polymarket_edge params, delivery channel limitations). This provides substantial meaning beyond the schema's generic 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 the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It clearly identifies the verb (create/subscribe) and resource (subscription), and distinguishes itself from siblings like list_subscriptions and unsubscribe.

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

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

The description provides context on when to use the tool (proactive monitoring) and prerequisites (Pipeworx OAuth account). It details supported types and delivery channels with examples. However, it does not explicitly state when not to use it or suggest alternative tools for one-off queries.

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 value by explaining the return structure (category-bucketed examples with tool+argument shape) and the educational context, going beyond annotations.

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

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

The description is a single paragraph that packs a lot of information (alternative phrasings, behavior, input options, output nature). It is efficient with no wasted words, though could be slightly more structured with bullet points.

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 single optional parameter, no output schema, and comprehensive annotations, the description fully covers the tool's purpose, input, output, and usage context. It leaves no gaps for an agent to misunderstand.

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, baseline is 3. The description adds meaning by listing the possible topic values and explaining that omitting gives a cross-category spread, which is not in the schema's description.

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

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

The description clearly states the tool returns category-bucketed example questions showing what Pipeworx can do, and positions it as an onboarding entry point. It distinguishes from siblings like ask_pipeworx and entity_profile by emphasizing examples and tool-argument shapes.

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 'Call with no arguments for the full spread' and 'pass `topic` to focus'. It also says 'Use this FIRST when you do not yet know what Pipeworx can do for you', providing clear when-to-use guidance.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds critical context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies the non-destructive, soft-delete behavior and links to a sibling 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 that are front-loaded and efficient. Every sentence adds unique information: purpose, ownership constraint, and behavioral nuance. 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?

For a simple single-parameter tool with no output schema, the description covers purpose, usage condition, and behavioral effect. It references relevant sibling tools and provides complete guidance.

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

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

With 100% schema coverage, baseline is 3. The description adds value by noting the id is a UUID and that it comes from subscribe, helping the agent understand the parameter's origin and format.

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 'Cancel a subscription by id', using a specific verb and resource. It naturally distinguishes from sibling tools like subscribe and list_subscriptions.

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

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

The description explains ownership enforcement ('you can only cancel your own subscriptions'), which guides when to use. It doesn't explicitly mention when not to use, but the condition 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?

The description goes far beyond annotations by detailing the return structure (verdict values, actual value with citation, reasoning), the special meanings of could_not_verify and unsupported, and how to interpret error payloads. It also reveals the tool replaces 4–6 sequential calls, giving useful context about its internal operation.

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

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

The description is dense but well-organized, opening with trigger phrases and then covering usage, return values, and edge cases. The 'IMPORTANT for callers' section is appropriately highlighted. A bit long, 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 no output schema and the tool's multi-path complexity, the description fully covers when to use it, what verdicts to expect, how to interpret edge cases, and parameter behavior. It leaves no important aspect unexplained for effective 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%, but the description adds meaningful operational detail for tolerance_pct, such as overriding the implied tolerance, the recommended range for hallucination detection, and the default cap. It also gives concrete claim examples for the claim parameter.

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

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

The description clearly identifies the tool as a claim-verification system, with specific trigger phrases ('fact check', 'verify the claim that...'). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on judging factual claims and describing two distinct verification pipelines (SEC EDGAR for financials, grounded pipeline for everything else).

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 'Use whenever the agent needs to check whether something a user said is factually correct' and gives examples of applicable claims. It explains the internal routing (financial vs. non-financial) but does not name alternative sibling tools for queries that are not claim verification, or explicitly state 'do not use when...'.

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