Intercom

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

Annotations already indicate safe, idempotent, non-destructive behavior. Description adds value by explaining default model, cost implication for Anthropic (BYO key), and return structure (per-model fields). No contradictions.

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

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

Four sentences, each earning its place: purpose, default behavior + key parameter, return format, use cases. No fluff, front-loaded with the core action.

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 the return structure (per-model fields plus combined view). Covers all 4 parameters, default behavior, optional enhancements, and appropriate use cases. Sufficient for an agent to invoke correctly.

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

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

Parameter schema has 100% coverage with descriptions. The tool description enriches each parameter with additional context: entity examples, model options and key requirement, API key passthrough, context purpose for disambiguation.

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

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

The description uses specific verb 'Probe' and resource 'LLMs for visibility', specifies return type (score 0-100 per model), and distinguishes from siblings by focusing on AI visibility scoring for marketing audits, pre-launch checks, and competitive monitoring.

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?

Clearly states use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains default model and optional Anthropic usage. Does not explicitly mention when not to use or alternatives, but the use case guidance is strong.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: it routes to sub-tools, auto-fills arguments, returns citations as stable pipeworx:// URIs, and is hallucination-resistant with grounded data. This aligns with and enhances the annotations without contradicting them.

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

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

The description is dense but well-organized: it front-loads the most critical decision (prefer over web search), then gives domains, trigger phrases, examples, and finally alternative-tool routing. Every sentence earns its place; there is no fluff or repetition of schema details.

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 extensive annotations (read-only, open-world, idempotent) and complete schema, the description covers what the tool does, when to use it, how it routes, and what it returns (structured answers with citations). It effectively compensates for the lack of an output schema by explicitly describing the response format. No critical decision-making information is missing.

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

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

Schema description coverage is 100%, so baseline would be 3. The description adds value by clarifying the parameter is a natural-language question and giving rich examples that inform what kind of question to provide. It doesn't detail parameter formats, but with only one core question parameter, the examples and trigger phrases already supply sufficient semantics 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 states a specific verb ('routes'), resource ('one of 5,767 tools across 1506 verified sources'), and outcome ('returns the structured answer with stable pipeworx:// citation URIs'). It clearly distinguishes itself from sibling tools like deep_research and ask_pipeworx_grounded by positioning itself as the default for factual, data-oriented questions.

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 'PREFER OVER WEB SEARCH' and provides extensive when-to-use guidance: data domains (SEC, FDA, FRED/BLS, patents, news, etc.), trigger phrases ('what is', 'look up', 'find', 'get the latest'), and concrete examples. It also gives when-not-to-use guidance by naming siblings: deep_research for broad multi-part questions, ask_pipeworx_grounded for evidence-grounded claims, and news-feeds packs for breaking news.

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?

It discloses that candidate routing improvements are enabled live during tests, that no candidate is currently active with a specific retirement date, and that results are compared against the stable router. This adds substantial behavioral context beyond the readOnly/idempotent annotations and clarifies that the tool is a full working router rather than a stub.

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 front-loads the beta identity and current experimental status before usage guidance. Each sentence contributes useful context, though the retirement date and 'falls back to nothing' clarification are slightly more detailed than strictly 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 the safe annotations, full schema coverage, and the sibling ask_pipeworx definition, the description covers identity, current state, usage, and argument/response equivalence. An agent has enough information to invoke it correctly, and no output schema is needed because the response shape is explicitly delegated to ask_pipeworx.

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

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

Schema description coverage is 100% and the parameters are described as the question plus aliases. The description only says 'same arguments' as ask_pipeworx without adding new parameter semantics, so the baseline of 3 applies.

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

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

Description identifies it as a beta universal router identical to ask_pipeworx with same tools, arguments, and response shape, so what it does is reasonably clear. It distinguishes itself as the experimental edge, though it relies on the sibling definition for the underlying 'ask a question, get routed result' semantics.

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

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

It says 'Use it exactly like ask_pipeworx when you want the newest routing', giving a clear condition and pointing to the stable alternative. It does not spell out an explicit when-not condition, but the experimental-vs-stable contrast 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?

Beyond the readOnly/idempotent hints, the description discloses refusal behavior, exact success/refusal response shapes, and the constraint that answers may only use tool-result content. It also names specific refusal reasons, which materially helps an agent predict failure modes.

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 earns its place: purpose, routing behavior, return contract, refusal reasons, use cases, and cost trade-off are all present. It is front-loaded with the core differentiator and ends with the practical selection rule.

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

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

With no output schema, the description fully specifies the success and refusal return shapes and even enumerates refusal reasons. It also covers when to prefer this tool, the cost implication, and the grounding constraint, so an agent has everything needed to invoke and interpret results.

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

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

Schema coverage is 100% and the schema fully documents the 'question' parameter and its aliases. The description adds no additional parameter-level guidance, but it does not need to; 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 defines a grounded, hallucination-resistant answer mode that routes, fetches, and extracts answers solely from tool results. It names the sibling ask_pipeworx and frames this as the grounded variant, so an agent can distinguish it without opening schemas.

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

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

Explicit usage criteria are given: use when an answer will be quoted, cited, or acted on in high-stakes contexts, with concrete domains listed. It also states a clear alternative and trade-off, preferring ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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 provided annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It details resolver behavior (market_match_confidence levels, suggestions), parent event extraction, news fallback mechanisms with retry logic, safety short-circuits for low-confidence matches and closed markets, wide spread warnings, and resolution-rule risk including void settlements. It also explains that the tool may block on certain conditions. This level of transparency is exceptional.

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. It opens with a clear one-sentence purpose, then uses section-like breaks (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) to organize extensive details. While some parts (e.g., fan-out examples) are verbose, they earn their place given the tool's complexity. The description is front-loaded with essential information and scales logically.

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

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

Given the tool's complexity (3 parameters, no output schema, rich annotations), the description is remarkably complete. It covers all aspects of usage: input resolution, classification, parallel data fan-out, analysis output with edge detection, response structure (market, analysis, evidence), error/edge cases (low-confidence, closed markets, wide spreads, cancellation rules), and resolver contract. No important behavior appears omitted.

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

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

The input schema already has 100% coverage with descriptions for all three parameters. The tool description adds meaningful context beyond the schema: it clarifies that 'market' accepts slug, URL, or question text; explains the difference between 'quick' and 'thorough' depth with example sources; and details the impact of 'include_raw' on response size and usability. While the schema provides baseline clarity, the description enriches understanding of parameter behavior.

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 primary function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies that it accepts a slug, URL, or question text, and that it returns an evidence packet and comparison. This is a specific verb+resource that distinguishes it from sibling tools like polymarket_edges or deep_research.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides practical guidance on inspecting the market_match_confidence field and warns about low-confidence resolutions, but does not explicitly contrast with sibling tools or state when not to use it. Despite that, the guidance is clear and actionable.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of citation URIs. No contradiction with annotations.

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

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

The description is well-structured, front-loading the purpose with example queries, but it is somewhat lengthy. However, every sentence adds value, so it remains efficient.

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

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

Given the tool's complexity, the description covers purpose, data sources, constraints, and output structure. It lacks details on error handling or edge cases, but for a 2-parameter tool with comprehensive annotations and schema, it is sufficiently complete.

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

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

Schema coverage is 100% with both parameters described. Description enhances meaning: explains that 'company' type pulls latest 10-K data and 'drug' type pulls FAERS data, and gives concrete examples for the 'values' parameter (e.g., tickers/CIKs, 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 uses specific verbs like 'compare', 'rank', and 'head to head', and provides example user queries. It clearly states the tool performs side-by-side comparison of 2–5 companies or drugs, distinguishing it from single-entity tools like entity_profile.

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

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

Explicitly advises to prefer this over sequential single-pack lookups for comparisons, and explains data sources for each type. Does not explicitly state when not to use (e.g., for more than 5 entities), but the schema constraints and mention of alternatives provide implicit guidance.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior, so the description's additional disclosures are valuable context rather than necessities. It adds rich details: account/payment requirements, laency expectations, gap reporting ('never invented'), contradictions[] handling, hop fields, and semantically excerpted large records. There is no contradiction with 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 long but every section is substantive: auth, alternatives, capability, return format, use cases, depth semantics, and timing. It is front-loaded with the most urgent info ('ACCOUNT REQUIRED') and then the differentiating 'NOT open-web search.' It could be slightly more compact, but no sentence is padding.

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?

This is a complex, high-stakes tool with no output schema, and the description compensates fully. It explains the findings packet structure, gaps and contradictions arrays, citation_uri resolvability, excerpting behavior, and timing. It also covers auth, cost, and when not to use the tool. An agent has everything needed to invoke it correctly and interpret results.

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

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

Input schema covers both parameters thoroughly, so baseline is 3. The description adds practical parameter-level knowledge: the paid requirement for depth:'thorough', typical latency ranges for each depth, and that deployment with 'stard' and 'thorough' adds contradiction scanning. These extras help an agent choose depth 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 a specific action and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search, which differentiates it from ask_pipeworx and other sibling tools. The tool's purpose is unambiguous and informative.

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 vs. when-not' guidance, including 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and guidance to prefer ask_pipeworx for breaking/colloquial current events. It also details when deep_research is best: 'for broad/multi-part questions over structured data.' This is exemplary routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond annotations by explaining that it returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples), and that each result is ready to call directly. 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 well-structured with the purpose first, followed by usage guidance and return details. It is fairly concise given the amount of information conveyed, though slightly verbose in listing domains. Every sentence serves a purpose.

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

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

Given no output schema, the description fully explains what the tool returns (top-N tools with names, descriptions, and full input schemas). It covers the primary use case of discovery, and the examples and domain list provide sufficient context for an agent to decide when to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions the 'query' parameter and provides examples, but does not add significant new semantics beyond what the schema and its descriptions already provide. The aliases are listed in the schema, not the 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's purpose: finding tools by describing data or task. It lists specific domains (SEC filings, FDA drugs, stocks, etc.) and distinguishes itself from sibling tools that answer specific questions or perform research. The verb 'discover' and the resource 'tools' are explicit.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. It also gives example queries. However, it does not explicitly state when not to use it or mention alternatives, though the context suggests it's for discovery before single-purpose 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?

Beyond the readOnly/idempotent annotations, the description discloses substantial behavior: fan-out across specific sources, per-source failure modes like USPTO sunset soft-fail and GDELT→GNews fallback, what an empty section means, and the resolved:false/notes behavior for private companies. This goes far beyond 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 dense and information-rich, but it is a single long paragraph with several redundant query examples ("research Acme", "brief me on Tesla", "company profile for Microsoft", etc.) that do not each earn their place. It would benefit from restructured bullets or trimming, though the content is relevant.

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

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

Despite having no output schema, the description enumerates the key returned sections, clarifies that sources_used/sources_failed indicate per-company reality, and covers input alternatives, failure behavior, and expected empty results. This is complete enough for an agent to call the tool correctly and interpret results.

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

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

The schema already covers both parameters well at 100% coverage, so the baseline is 3. The description adds meaningful extra context: concrete token/CIK/name examples, that `type` values are interchangeable, and how names resolve through SEC EDGAR, including the private-company edge case.

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

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

The description states a specific action and resource: building a full cross-source profile of a US public company in one parallel call. The opening examples make the trigger queries unmistakable, and the ALWAYS PREFER directive distinguishes it from chaining single-purpose SEC/XBRL/news lookups.

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

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

It explicitly says to use this tool when the user wants a holistic view and to prefer it over chaining single-pack lookups. It also explains acceptable input forms and the private-company fallback, so an agent knows when the tool is appropriate and what to expect when it isn't.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the specific deletion action, which is consistent but adds little beyond annotations. No contradictions.

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

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

Three sentences front-loaded with purpose, no wasted words. Every sentence adds value.

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

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

For a simple single-parameter deletion tool with comprehensive annotations, the description covers purpose, usage, and related tools adequately. No output schema needed.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The tool description does not expand on the parameter beyond what the schema provides, so baseline is appropriate.

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

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

The description clearly states the action ('delete') and the resource ('memory by key'), distinguishing itself from sibling tools like 'remember' and 'recall' by pairing them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with 'remember' and 'recall,' providing clear context for alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context by explaining the extraction process and output format, but does not cover rate limits or auth requirements.

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

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

Two concise sentences: first explains the tool's action and output, second lists use cases. No unnecessary words, and the important information is front-loaded.

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

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

Given no output schema, the description adequately explains the return format ('single text blob') and mentions the standard markdown format. It does not address error cases or specific failure modes.

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

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

With 100% schema description coverage, the schema already documents both parameters. The description provides no additional parameter-level details beyond what is in the schema.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the action of fetching a page and extracting metadata. It distinguishes from sibling tools like 'scan_competitor_ai_presence' by specifying the output format and use cases.

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

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

The description provides explicit use cases (client indexing, personal drafting, competitor auditing) but does not mention when not to use or compare with alternatives like 'scan_competitor_ai_presence'.

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. The description adds value by listing the specific data returned (including conversation history), which annotations do not cover. No contradictions.

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

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

The description is a single sentence with a bullet-style list of return fields. It is front-loaded with the core purpose and all information is valuable and non-redundant.

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

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

Given the simple one-parameter input, the presence of an output schema (which likely details return structure), and comprehensive annotations, the description sufficiently covers what the tool does and returns. No important gaps.

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

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

Schema coverage is 100% and the single parameter 'id' is described with a brief explanation ('Contact ID') in the schema. The description adds no further semantic detail about the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool gets full contact details by ID and lists specific return fields (name, email, phone, attributes, tags, conversation history). This distinguishes it from siblings like ic_search_contacts (search) and ic_get_conversation (conversation-specific).

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

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

No guidance on when to use this tool versus alternatives such as ic_search_contacts or ic_list_companies. While the purpose is clear, the lack of explicit when-to-use or when-not-to-use advice reduces usability for an agent deciding between 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds detail on returned content (messages, timestamps, participants, metadata), which aligns with annotations. No contradictions.

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

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

Two sentences, front-loaded purpose, no unnecessary words. Efficient and clear.

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 presence of output schema, description adequately covers what the tool returns. Complete for a retrieval tool.

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

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

Only one parameter (id) with schema coverage 100%. Description adds minimal value beyond schema (just 'by ID'). 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?

Title and description clearly state 'Get complete conversation thread by ID' with specific returns (messages, timestamps, participants, metadata), distinguishing it from sibling tools like ic_list_conversations.

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 implies use when you have a conversation ID and need full details. It does not explicitly state when not to use or mention alternatives, but context with siblings provides some guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds return field details but no additional behavioral context beyond pagination, which is already implied by parameters.

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

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

Description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and return fields.

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

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

For a simple listing tool with two parameters and an output schema implied in the description, it covers the essential aspects. Lacks details on ordering or filtering, but these may not be needed given the tool's simplicity.

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

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

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description does not add new meaning beyond the schema's parameter descriptions.

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

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

Description clearly states the tool lists companies with pagination and specifies returned fields. It is specific to listing companies, distinguishing it from sibling tools like ic_search_contacts, though not explicitly contrasting 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?

No usage guidance is provided. The description does not mention when to use this tool versus alternatives, nor any prerequisites or 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?

Annotations already declare this as read-only, idempotent, etc. The description adds return field details but doesn't disclose any other behavioral traits like pagination characteristics or potential rate limits. It provides modest additional context.

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

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

The description is very concise with a single sentence that covers the tool's action and return values. No wasted words, though it could be structured slightly more for readability.

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

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

Given the output schema exists, the description sufficiently covers the tool's purpose and return fields. It mentions pagination but could clarify cursor behavior. Overall, adequate for a simple list tool.

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

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

Schema coverage is 100%, so the description doesn't need to add much. It mentions pagination but doesn't elaborate on parameter usage beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'conversations', and specifies the returned fields. While it doesn't explicitly differentiate from sibling tools like ic_get_conversation, the function name and return info make it 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?

No guidance is given on when to use this tool versus alternatives, such as ic_get_conversation for a single conversation or other list tools. The description only implicitly conveys usage through the verb 'List'.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by specifying return fields (contact ID, name, email, metadata), though it omits pagination or limit details.

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: first states purpose and search criteria, second lists return fields. No extraneous words, front-loaded with key information.

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

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

For a simple search tool with comprehensive annotations and output schema, the description is nearly complete. Minor omission of result size or pagination behavior, but sufficient for most use cases.

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

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

Schema coverage is 100% with a single 'query' parameter. The description enhances by mentioning 'custom attributes' as a search field, adding specificity beyond the schema's 'other field'.

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

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

The description clearly states the tool searches for contacts by name, email, or custom attributes, and distinguishes from sibling tools like ic_get_contact which retrieves a single contact by ID.

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

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

The description implies when to use (searching contacts), but does not explicitly state when not to use or mention alternatives like ic_get_contact for known IDs.

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, and non-destructive. The description adds value by listing the response fields, which aids understanding beyond the annotations.

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

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

The description is two sentences, front-loading the core purpose and return fields, then providing usage guidance. No extraneous text.

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

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

Despite lacking an output schema, the description lists all returned fields. It also includes usage context. For a simple list tool with one optional parameter, this is 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?

There is only one parameter, and its schema description is fully covered (100%). The tool description does not need to add further meaning since the schema already explains it adequately.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). It distinguishes itself from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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 the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and alternatives.

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

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

Annotations are all false and offer little, so the description carries the full burden. It discloses the claim_token return flow, rate limiting ('5 per identifier per day'), daily digest processing, and that it is free and does not count against the tool-call quota—all beyond the structured fields. 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 (~200 words) but every sentence carries operational value: use cases, exclusions, content rules, token flow, rate limits, and cost. It is front-loaded with purpose; minor redundancy in the roadmap-motivation sentence prevents a perfect score.

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 explaining the claim_token response pattern and the resolution loop. It also covers the nested context object's role (referencing Pipeworx tools/packs) and the required content style, making the tool fully self-contained for an agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds workflow meaning for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed') and practical guidance for message length ('1-2 sentences typical'), which enriches the schema's existing constraints.

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

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

The description opens with a clear verb+object: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete feedback types (bug, feature, data_gap, praise) and explicitly scopes the tool to Pipeworx's own tools and packs, which distinguishes it from all sibling research and query tools.

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

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

Provides explicit triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states a clear exclusion—feedback for other MCP servers should be filed there—and offers a disambiguation rule ('Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, caching duration (5min-1h), and that it's derived from (pack, tool, count). 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?

Concise, front-loaded with the key output, uses a numbered list for use cases, and every sentence adds information. No wasted words.

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

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

Given the tool's simplicity (1 optional parameter, no output schema), the description fully covers purpose, usage, behavioral traits, caching, and privacy. No missing elements for an agent to use this tool effectively.

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

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

Schema covers the single parameter with enum and description (100% coverage). The description adds value by explaining the behavioral difference between shorter and longer windows (short: hot right now; long: steady-state demand), which goes beyond the schema's generic 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 top tools, top packs, and total call volume over a time window. It distinguishes itself from siblings like discover_tools by focusing on trending usage rather than discovering available 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 lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains window behavior differences. Does not provide explicit when-not-to-use scenarios, but the read-only nature makes that less critical.

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 as true and destructiveHint as false. The description adds significant behavioral context: walks child markets, computes partition checks, semantic anchor using Jaccard similarity, partition filter for placeholder slugs, and fill check against CLOB depth. No contradiction; annotations align.

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

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

The description is well-structured, front-loading the main purpose and then detailing modes, partitions, semantic anchor, and fill check. Every sentence adds value, though it is somewhat dense; a minor reduction in detail could improve conciseness without losing clarity.

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

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

For a complex tool with no output schema, the description thoroughly details the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity violation context; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade; and fill check details. This provides complete contextual understanding.

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

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

Schema description coverage is 100% with both parameters documented. The description greatly enhances meaning: explains that event mode walks child markets, checks date-axis/threshold-axis ordering, computes partition_check; and topic mode searches related events, flattens markets, runs comparator. Also notes accepted input formats like full Polymarket URLs.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes: no args for trending scan, event for specific market, and topic for cross-event scanning, setting it apart from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance is provided for each mode: no args for trending scan, event (recommended) for a specific market, topic for cross-event scanning. It explains why cross-event mode catches patterns single-event misses, and warns against trading when fill check shows realizable_edge_pp ≤ 0, also referring to polymarket_fill_risk for custom sizing.

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

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

The description discloses extensive behavioral traits not covered by annotations (readOnlyHint, etc.), such as caching behavior ('Cached 1h at the KV level keyed on all knobs'), detailed model families and their properties, diagnostics provided ('_diagnostics so callers can see WHY a segment is empty'), and edge case handling (Fed bets excluded, partitions with >20% placeholder skipped). 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 quite lengthy and dense with technical details about models and segments. While it is front-loaded with the purpose, the extensive detail may be overwhelming and could be more concise for efficient agent parsing.

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 (9 parameters, no output schema), the description covers all necessary aspects: model families, response segments, diagnostics, caching, knobs for filtering, and edge cases. It provides a complete picture for an AI agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with each parameter having a description in the input schema. The description adds context by referring to parameters as 'knobs' and grouping them (e.g., 'tradeable-edge knobs'), but does not provide significant new meaning beyond the schema's own 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 begins with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', which clearly states the verb (scan/return), resource (Polymarket markets), and its unique value proposition (disagreement detection). This distinguishes it from sibling tools like polymarket_arbitrage by its specific focus on Pipeworx disagreement.

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 it is 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets', providing a clear use case. However, it does not explicitly mention when not to use this tool or suggest alternatives for other polymarket-related tasks.

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 idempotentHint=true, so the description adds significant behavioral context beyond these: historical depth bounded by a 60-day TTL, snapshot generation on cache-miss, decay computation from daily closes, and explanation of fields like trend and decay_pp_per_day. No contradiction with annotations.

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

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

The description is well-structured, starting with the core question, then detailing response structure and limits. Every sentence is informative, but the length is slightly verbose for a tool description. A minor reduction could improve conciseness while retaining all information.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), field semantics (e.g., sign of decay_pp_per_day), and limitations (TTL, snapshot start). It is comprehensive for a complex tool, leaving no major gaps for an agent to understand its behavior.

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

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

Schema description coverage is 100% for both parameters, so baseline is 3. The description restates defaults and ranges (e.g., 'default 14, max 30') but does not add new meaning beyond the schema's clamp and default descriptions. It adds minimal extra value.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering the specific question about how long an edge has existed and whether it is shrinking. This distinguishes it from sibling tools like polymarket_edges, which likely provides current edges, by focusing on historical analysis.

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

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

The description explicitly frames the tool's usage around answering whether an edge is fresh or old, providing clear context. While it does not explicitly state when not to use it or name alternatives, the sibling tool context implies alternatives, and the description's framing is sufficiently clear for an agent to determine appropriate use.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral detail: walks the ladder, returns specific fields (slippage, fill details, verdict), and warns about 'thin_legs' and 'forced_directional_risk' for basket mode. No contradictions.

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

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

The description is a single dense paragraph but well-structured with uppercase section headers (REQUIRES, SINGLE-MARKET, BASKET). Every sentence adds value, though it could be slightly more concise. No wasted text.

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

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

Despite the lack of an output schema, the description comprehensively lists all return fields for both modes, explains the verdict system, and covers the risks of partial fills. For a complex tool, this is a complete and actionable description.

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%. The description adds extra meaning: default values (size_usd=1000), clamps (10–1,000,000), clarification of side default behavior in basket mode (auto), and interpretation differences between single and basket modes.

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 order-book depth, with specific modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating when to use it before those signals.

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

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

The description provides explicit guidance: use before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. It also explains the consequences of not using it (partial fills converting arb to directional position) and notes the requirement for `market` or `event`.

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

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

Annotations already declare read-only, open-world, and idempotent behavior; the description adds substantial context beyond that: compatibility warnings, machine-readable codes, skipped leg counters, fee-schedule disclosure, null temporal alignment semantics, and pairing verification caveats. No contradiction with annotations.

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

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

The description is long and dense, but it is organized with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core purpose. The length is justified by the tool's complexity, and almost every sentence conveys operationally relevant 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?

There is no output schema, yet the description documents response fields, safety fields, per-entry flags, skipped categories, fee model limitations, and temporal alignment semantics. An agent has enough context to call the tool and interpret results correctly, including edge cases where matches are returned but warnings still apply.

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 baseline is 3. The tool description mostly repeats the topic list and override semantics already present in the schema, adding only a caution that most pre-mapped topics currently return compatibility warnings. It does not meaningfully enrich parameter meaning beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific modes and output behavior. It does not explicitly distinguish itself from sibling tools like polymarket_arbitrage, so it stops short of full 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 gives clear context on when to use topic shortcuts versus explicit event pairings, and warns that pre-mapped is not necessarily tradeable. However, it never names alternatives or states when not to use this tool compared to siblings, so usage guidance is implied rather than explicit.

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 behavioral context beyond annotations: scoping by identifier, listing behavior when key omitted. No contradiction with readOnlyHint, destructiveHint, idempotentHint.

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

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

Three sentences, front-loaded with main purpose, no wasted words. Efficient structure.

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 low complexity (1 optional param, rich annotations), description covers purpose, usage, pairing, scoping. Complete for effective use.

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

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

Schema coverage is 100% with clear description for 'key'. Description adds the same info (omit key to list all keys). No additional 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?

Description clearly states verb (retrieve/list) and resource (saved values/keys). Distinguishes from sibling tools remember and forget by mentioning 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?

Provides clear context for when to use: 'look up context stored earlier without re-deriving'. Mentions pairing with remember/forget but does not explicitly state when not to use.

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

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

Annotations already indicate safe read operation; description adds details on returned fields (source, citation_uri, payload) and mark_read effect on subsequent calls. 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?

Concise multi-sentence structure: main purpose first, then return details, parameter usage, mark_read behavior, polling guidance, and alternative access. 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?

Covers return fields, parameter effects, and polling suitability despite no output schema. Missing pagination detail but schema already describes limit. Adequate for tool complexity.

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

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

Schema covers 100% of parameters; description reinforces their purpose (e.g., filter by type, since, mark_read). Adds clarity on mark_read impacting next call, slightly exceeding schema 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?

Starts with 'Pull fired events from your subscription feed,' a specific verb+resource. Clearly distinguishes from siblings by focusing on subscription feed alerts, filtering, and mark_read behavior.

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

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

States polling works fine and mentions alternative URL for scripts/dashboards, offering usage guidance. Doesn't explicitly differentiate from sibling tools like recent_changes or subscribe, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial context: parallel call, fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, and accepted date formats. 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 well-structured, starting with example queries, then explaining functionality and fallback, then parameter details, then comparison with sibling. Every sentence adds value, though slightly verbose for some readers.

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 return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs), covers all sources and fallback, addresses parameter formats, and contrasts with entity_profile. Complete for the tool's complexity.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra meaning: typical `since` values ('30d' or '1m'), explanation that `type` only supports 'company', and clarifies `value` accepts ticker or CIK. This goes 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?

The description provides specific verb phrases ("What's new with X", "latest on Y") and clearly states the tool aggregates change feeds from SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes from sibling tool entity_profile.

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

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

The description includes explicit when-to-use guidance with real query examples and contrasts with entity_profile: 'Use entity_profile instead when you want the static profile...'. No ambiguity about 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?

Adds key behavioral details beyond annotations: scoping by identifier, retention policy (24 hours for anonymous, persistent for authenticated). Annotations already cover idempotent and non-destructive nature.

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

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

Four sentences, each earning its place: purpose, when-to-use, storage details, pairings. No redundancy or fluff.

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

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

For a simple store tool with no output schema, the explanation of purpose, usage, scoping, retention, and companion tools is fully adequate.

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

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

Schema coverage is 100%, so description adds minimal new info beyond parameter names and types. Example key patterns in schema description are helpful but not extraordinary.

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 'Save data the agent will need to reuse later' and distinguishes from siblings recall and forget by mentioning them and contrasting use cases.

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

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

Provides explicit guidance on when to use ('when you discover something worth carrying forward') and example scenarios, but lacks explicit 'do not use' cases.

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 well beyond the readOnly/openWorld/idempotent annotations by explaining graceful degradation, cascading lookup behavior, source-labelled identifiers, explicit unresolved fields, and ambiguity handling with figi_candidates. This gives an agent an accurate mental model of side effects and edge cases without contradicting 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 long and dense, but it is front-loaded with purpose and usage and every clause carries useful detail. It is somewhat verbose and could be tightened, but the structure is logical and the parenthetical specifics are valuable rather than padding.

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 present, the description carries the burden of explaining return behavior, and it does so thoroughly: identifier types, sources, unresolved results, ambiguity candidates, and enrichment failure modes. For a tool with this complexity, nothing critical is missing for an agent to invoke it 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?

Although schema coverage is 100%, the description adds substantial meaning to both parameters: accepted input forms for company values, brand vs generic drug names, and the crucial 'entity name only' constraint for bonds. It also clarifies how inputs like ISIN and CIK behave, which the schema does not convey.

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

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

The description states a specific verb and resource: resolving user-spoken names to canonical identifiers. The opening examples and 'Use FIRST whenever you have a name but need an ID' make it easy to tell apart from the sibling tools, even without naming them explicitly. It also enumerates the supported entity types, so an agent can immediately recognize the tool's niche.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when the tool should not assert a single bond, returning figi_candidates instead. However, it does not name alternative sibling tools or provide explicit when-not-to-use conditions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond by revealing it probes each entity with 'ai_visibility_check', ranks by score, and surfaces recognition. No contradictions and adds valuable procedural context.

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

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

Three sentences, front-loaded with the primary action, no filler. Every sentence earns its place, covering purpose, method, and use case 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?

With four parameters, no output schema, and strong annotations, the description covers the workflow (probe, rank, return), use case, and output details (score, confidence, signal density). Lacks exact output format but is 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%, but the description adds meaning beyond the schema: it explains the first entity is treated as 'subject', that 'models' is optional, and 'context' disambiguates. This extra context aids selection.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' with a specific verb and resource, and distinguishes itself from sibling tools like 'ai_visibility_check' (single probe) and 'compare_entities' (generic comparison).

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and an example question, implying when to use it. It lacks explicit when-not-to-use or direct alternatives but still offers strong guidance.

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

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

Annotations already provide readOnlyHint, openWorldHint, etc. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed field lists timeouts. 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 front-loaded with purpose, followed by usage, ecosystem scope, and failure behavior. Every sentence adds essential information without redundancy. Well-structured for an AI agent.

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

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

Despite having no output schema, the description thoroughly enumerates return fields (summary block, per-advisory, links, alternatives) and explains edge cases (partial failures, latency). Fully covers the tool's behavior given its complexity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted, providing additional clarity beyond the schema.

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

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

The description clearly states it's a composite check for npm packages using deps.dev and bundlephobia. It uses specific verbs ('scan', 'fans out', 'returns') and distinguishes itself from sibling tools, none of which cover dependency scanning.

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 agent asks is X safe/popular/small') and provides exclusions ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). This gives 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?

Adds details beyond annotations: offsets for verification, embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K) with truncation and flagging. Annotations already declare idempotency and read-only, so 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?

Six sentences, front-loaded with purpose and usage guidelines, then technical details. Every sentence adds 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?

Covers parameters, behavior, and some output details (offsets, similarity scores). Lacks explicit output schema structure but provides enough for selection and basic use. Minor gap given no output schema.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description adds no new meaning beyond the schema; it elaborates on use case but not on parameter syntax or constraints.

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 does semantic search inside a fetched record, using a natural-language query to return passages. It distinguishes from siblings like ask_pipeworx_grounded by specifying that it searches within already-pulled text.

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 to use when the record is too big for the prompt, saving context. Mentions pairing with ask_pipeworx_grounded and implies not to use when the record fits directly.

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

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

The description adds behavioral context beyond annotations, such as delivery channel limitations (10/day SMS cap, webhook auto-disable after 10 failures) and prerequisites (phone verification). Annotations indicate idempotency, which is not reinforced but not contradicted.

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

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

The description is well-structured, front-loaded with the core purpose, and provides examples without excessive verbosity. While long, every sentence adds value, though some inline examples could be shortened or moved to schema.

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

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

Despite the complexity (multiple types, delivery channels, nested parameters), the description covers all major aspects: requirements, type-specific params, return value, and delivery behavior. Missing details like error handling are acceptable without an output schema.

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

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

Schema coverage is 100%, and the description adds significant meaning by providing specific examples for each subscription type (e.g., sec_8k items codes, FRED series_id). This goes 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 clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific verb ('Create') and resource ('subscription'). It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context for use, including account requirements (Pipeworx OAuth) and supported types with explicit examples. However, it does not explicitly state when not to use this tool or suggest alternatives, though the sibling context implies other operations.

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, openWorld, idempotent, destructive hints. The description adds concrete output behavior (category-bucketed examples from live catalog) without contradicting annotations.

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

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

The description is somewhat long but well-structured, front-loading example queries and then explaining the tool's function. Each sentence adds value, 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?

Given the tool's simplicity (1 optional param, no output schema), the description fully covers purpose, usage, output content, and context. It lists categories and explains when to call it, leaving no gaps.

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

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

Schema coverage is 100% with a detailed description of the optional 'topic' parameter. The description enhances by listing example values and explaining its focusing effect, adding value beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with exact tool and argument shapes, positioning it as an onboarding entry point. It distinguishes itself from siblings like 'discover_tools' by specifying it's for learning what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and to learn how to call meta-tools. Also indicates when to omit or pass the 'topic' parameter, providing clear guidance.

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

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

The description adds context beyond annotations by clarifying that the subscription is deactivated (not deleted) and historical events persist. Annotations already indicate non-destructive mutation, but description enriches understanding.

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

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

The description is two sentences with zero redundant information. Every word serves a purpose: action, ownership, behavior, and consequence.

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

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

For a simple tool with one required parameter and no output schema, the description covers all essential aspects: operation, ownership constraint, side effects, and parameter origin.

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 sole parameter 'id' is well-described in the schema as 'Subscription id (uuid) returned by subscribe.' The description reinforces this by referencing 'subscribe' tool. Schema coverage is 100%, so baseline is 3; description adds minor extra context.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription by id'. It 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?

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the behavioral distinction from deletion ('deactivated not deleted'), guiding appropriate 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals valuable behavioral details: two distinct execution paths, the full verdict set, citation and reasoning in the output, and the crucial nuance that could_not_verify indicates an execution failure rather than evidence for/against the claim. This goes far beyond what annotations convey.

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

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

The description is front-loaded with natural-language trigger examples ('Is it true that…', 'fact check'), making the tool's purpose immediately recognizable. Every subsequent sentence adds necessary detail: usage guidance, routing logic, verdicts, evidence, the critical could_not_verify caveat, and the efficiency claim. The length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by enumerating all possible verdicts, describing the return bundle (value + citation + reasoning), and explaining the difference between could_not_verify and unsupported. It also covers the two major claim categories and the fallback behavior, making the tool's behavior fully transparent for an agent.

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

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

The input schema already provides 100% coverage for both parameters, with clear descriptions and examples for claim and tolerance_pct. The description adds only marginal semantic context, such as 'exact percent-delta math' and the override behavior for tolerance_pct, which are also present in the schema. Baseline 3 applies.

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

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

The description clearly defines the tool as a natural-language claim verification service, using specific verbs like 'validate', 'check', and 'confirm/refute'. It distinguishes itself from generic Q&A tools by explaining the two routing paths (SEC EDGAR/XBRL for financial claims, grounded pipeline for others) and explicitly notes it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct.' It also provides usage sub-guidance for financial vs. non-financial claims. However, it does not explicitly mention alternatives or when NOT to use this tool in favor of a sibling tool.

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