Apis Guru

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context: default model (Workers AI Llama-3.3-70b, free), optional Anthropic with key, that Anthropic calls are paid directly by user. 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 four sentences, front-loaded with purpose, then details. Every sentence adds value: what it does, default model, optional Anthropic, return format, use cases. No unnecessary words.

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

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

Given the tool complexity (4 params, full schema coverage, no output schema), the description fully covers: purpose, parameters, return format (per-model {score, confidence, signals, raw_response} + combined view), use cases. 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?

All 4 parameters have descriptions in the schema (100% coverage). The tool description enriches understanding: context 'disambiguates common names,' models lists supported values, _apiKey explains it is passed through. This adds value beyond the schema.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the action (probe, score), resource (LLMs), and output (per-model results with combined view), distinguishing it from similar tools like scan_competitor_ai_presence.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and optional Anthropic probing with BYO key. However, it does not directly compare to sibling tools or state when not to use it, missing an opportunity for fuller 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 establish read-only, open-world, and idempotent behavior. The description adds valuable context: it routes to thousands of tools, returns pipeworx:// citation URIs, works on every tier, and is a single fast call. That goes beyond the annotation baseline without contradicting it.

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

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

The description is longer than necessary but front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Each sentence earns its place by adding examples, alternatives, or scope, though a slightly tighter version could be equally effective.

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

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

For a complex, default entry-point tool with no output schema, the description covers purpose, usage, alternatives, examples, output format, and limitations (e.g., breaking news). It leaves the agent with a clear mental model of when and how to invoke 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%, and the description does not add additional parameter-level detail beyond the question examples. The schema already documents aliases, so the description gains no extra points here, but it also doesn't harm clarity.

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 role: routing factual questions to a large set of verified sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for different needs.

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

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

Provides explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'get the latest'), concrete examples, and a clear 'START HERE' directive. It also explains when to step up to alternative tools, making the decision criteria unambiguous.

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 readOnlyHint and idempotentHint annotations, the description discloses that this is an experimental edge with live routing improvements when under test, and that it currently matches stable behavior because the last candidate was retired. It also explicitly states 'Falls back to nothing — this IS a full working router,' addressing potential concern about degraded functionality.

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 several sentences long but each adds context: beta status, identical behavior, current no-candidate state, usage guidance, and no-fallback assurance. It could be tightened slightly, but it's well organized and front-loaded with the most important information.

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

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

Given the rich schema and annotations, the description provides all necessary context: what the tool is, how it relates to ask_pipeworx, when to use it, current behavior, and the fact that it's a complete router. The mention of 'same response shape' addresses the lack of an output schema. It's complete for an experimental variant.

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 has 100% coverage with all six parameters described as aliases for question. The description adds no additional parameter syntax or semantics, which is fine because the schema already fully documents them. 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 identifies this as a beta version of ask_pipeworx, a universal router with 5,462 tools, and explicitly distinguishes it from the stable ask_pipeworx sibling by noting candidate routing improvements. The phrase 'identical universal router' plus 'experimental edge' makes the purpose specific and usable.

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

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

The description states when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also clarifies that currently no candidate is active, so behavior matches ask_pipeworx exactly, giving concrete guidance on current 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, idempotent, not destructive), it discloses the full response structure, refusal_reason enum values, dependency on only tool content for answers, and the extra LLM call cost. 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?

Every sentence serves a distinct purpose: function definition, mechanism, return format, use cases, and cost tradeoff. It is dense but scannable, front-loaded with the core purpose, and contains no filler.

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

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

The tool is complex with no output schema, but the description fully covers success and failure modes, return fields, refusal reasons, routing behavior, and usage tradeoffs. It is self-sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with all six parameters described as aliases of 'question.' The description adds no additional parameter-specific semantics; it only implies the question is in natural language, which the schema already states. 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 opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by detailing that it extracts answers strictly from tool results and includes refusal paths, making its unique value 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims). Also gives an exclusion: 'prefer ask_pipeworx for casual lookups.'

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 extensive behavioral details: fan-out logic, response shapes, resolver contract, parent_event extraction, news fallback fields, safety mechanisms for low-confidence matches, closed market handling, wide spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and uses uppercase headings. Every sentence adds value for a complex tool. While not concise, the structure aids 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 no output schema, the description thoroughly explains response shapes, edge cases (low confidence, closed markets, wide spreads, resolution rules), and behavioral details. Covers all aspects an agent needs to invoke and interpret results correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining input formats (slug, URL, question text) for 'market', enum values for 'depth', and detailed context for 'include_raw'. Examples further clarify usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies verb (research), resource (Polymarket bet), and differentiates from siblings like polymarket_edges and polymarket_arbitrage by focusing on a single bet's data pull.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides contextual guidance on inspecting market_match_confidence and parent_event. Lacks explicit when-not-to-use or alternatives, but clear enough for an agent.

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

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

Beyond annotations (readOnly, idempotent, openWorld, non-destructive), description discloses data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results by primary metric, and citation URIs. No contradictions with annotations.

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

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

Description is dense with useful information but could be slightly more concise. Key purpose and usage are front-loaded with examples, making it effective despite length.

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

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

For a comparison tool with no output schema, description fully explains return format (paired data with citation URIs) and behavior (sorted results), making it self-contained and 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 clear descriptions for both parameters. Description adds value by giving concrete examples (tickers/CIKs for companies, drug names) and specifying max/min items, but schema already covers basics.

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

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

Description clearly states it performs side-by-side comparison of 2–5 entities (companies or drugs) with specific metrics per type. Distinguishes from sibling tools by explicitly preferring over sequential single-pack 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?

Provides explicit query examples ('X vs Y', 'which is bigger') and states when to use ('ALWAYS PREFER over sequential single-pack lookups'). No ambiguity about usage context.

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

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

Despite readOnlyHint=true and openWorldHint=true annotations, the description adds substantial behavioral detail: parallel facet decomposition, 5,462 tools, citation format with pipeworx:// URIs, gaps[] for unanswered facets, contradictions[] in standard/thorough, semantic excerpting, hop field, and timing expectations. It discloses that results may be empty for non-structured topics and that depth:'thorough' requires a paid plan.

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

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

The description is long but information-dense; every sentence adds distinct value about use cases, limitations, citation behavior, or depth semantics. It front-loads critical access requirements and the NOT open-web disclaimer, though it could be tightened slightly to reduce reading fatigue.

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 2 parameters and 100% schema coverage, this description is exceptionally complete. It covers prerequisites, alternatives, expected latency, output structure, edge cases (gaps[], contradictions[]), and even disambiguates from similar tools. The lack of an output schema is compensated by a detailed description of what the findings packet contains.

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%, listing both parameters with their own descriptions. The description goes further by explaining how depth values affect hops: 'quick' single hop, 'standard' gap recovery + contradictions, 'thorough' iterative lead-chasing + contradictions. It also clarifies that broad/multi-part questions in natural language are supported, adding meaning beyond the raw schema.

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

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

Clearly states it performs grounded multi-source research across Pipeworx's structured data sources, decomposes questions into facets, routes to tools in parallel, and returns a findings packet. It distinguishes itself from siblings like ask_pipeworx by emphasizing it is NOT open-web search and is best for broad/multi-part structured-data 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?

Provides explicit when-to-use guidance: broad/multi-part structured questions ('compare X and Y's regulatory + financial exposure'), and explicitly says to use ask_pipeworx for single lookups or breaking/colloquial current-news topics. It even covers account-tier requirements and alternatives, making the decision boundary crystal 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?

Discloses beyond annotations: results include full input schemas with examples, ready to call directly. Annotations indicate read-only, idempotent, non-destructive; description adds context on output format and usage order.

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

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

Single paragraph but well-structured: purpose first, then usage guidance, then results details. No wasted words, though slightly dense. Effective.

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

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

Given no output schema, the description adequately explains return value (top-N relevant tools with schemas and examples). Covers purpose, usage, expected output, and position among sibling tools. 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 100% with aliases documented. Description adds value by listing example queries and explaining limit parameter. Baseline 3 for high coverage; extra examples and alias explanation merit 4.

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

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

The description clearly states the tool finds tools by describing data or task, with specific verbs like browse, search, look up, discover. It distinguishes from sibling tools as a meta-tool for discovery.

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

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

Explicitly tells when to use: when needing to browse/search/discover tools for specific domains, and advises to call FIRST before using other tools. No alternative needed as it's the entry point.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it describes parallel fan-out across SEC, XBRL, USPTO, news, GLEIF; mentions soft-fail for patents post-May 2025; specifies return fields including recent_filings with URLs; and notes that only US public companies are supported. 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 paragraph of about 5-6 sentences. It is front-loaded with example queries and key instructions. While it covers necessary information efficiently, it could benefit from bullet points or a more structured format for easier scanning. Overall, it earns its sentences.

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

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

Given the tool's complexity (multiple data sources, fallback mechanisms, specific return fields), the description provides complete context without needing an output schema. It explains data sources, return fields, limitations (e.g., patents soft-fail), and input constraints. The agent has sufficient information to use the tool correctly.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning beyond schema by clarifying that the 'type' parameter only accepts 'company' for now, and that the 'value' parameter expects a ticker or zero-padded CIK, not a company name. This additional context raises the score.

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 ('fan out', 'return', 'pass') and clearly identifies the resource ('full cross-source profile of US public company'). It distinguishes from sibling tools like resolve_entity by stating names are not supported, and lists multiple data sources. Examples such as 'Tell me about X' and 'research Acme' make the purpose unmistakable.

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

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

Explicitly states when to use ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to ('names not supported – use resolve_entity first if you only have a name'). Also provides input format requirements (ticker or zero-padded CIK).

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

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

Annotations provide destructiveHint=true and idempotentHint=true; description adds context about clearing sensitive data saved earlier. No contradictions, but doesn't detail behavior for missing keys.

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

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

Two sentences that are concise and front-loaded with the core action. Every sentence adds value: action, when to use, and sibling guidance.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage context, and behavioral cues. No gaps 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 a single 'key' parameter described as 'Memory key to delete'. Description adds little beyond restating 'by key', so baseline 3 is appropriate.

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

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

Description states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings like 'remember' and 'recall' by mentioning pairing, and the sibling list confirms 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?

Explicitly says when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with remember and recall, but does not provide when-not-to-use scenarios.

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

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

The description discloses that the tool fetches an external page, extracts title/description/key links, and emits standard markdown. This adds context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint) by detailing the read operation's scope and output format. No contradictions with annotations.

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

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

The description is a single, well-structured paragraph that front-loads the main purpose and then provides process details and use cases. It is concise but could be slightly trimmed without losing essential information.

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

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

Given the tool's simplicity (2 params, no output schema), the description adequately covers purpose, process, output format, and use cases. It does not address error handling or edge cases, but for a generative read-only tool this 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?

The input schema covers both parameters with descriptions (100% coverage). The description adds value by explaining the output context (a text blob ready for site-root/llms.txt) and hinting at the purpose of max_links. Though schema already describes max_links, the description reinforces its usage.

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

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

The description uses a specific verb ('Generate'), names a clear resource ('llms.txt file'), and explicitly states the target action for AI crawlers. It also lists steps (fetches, extracts, emits) and distinguishes from siblings like 'ai_visibility_check' or 'scan_competitor_ai_presence'.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt... or auditing how an AI crawler would see a competitor'), which gives clear when-to-use guidance. It does not include when-not-to-use or direct alternatives, but the sibling list includes related tools that could be contrasted.

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, and non-destructive behavior. The description adds valuable details about what is returned (every version, info, last-updated, spec URLs, preferred version), which is consistent 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?

Two sentences: first explains the action with examples, second provides usage context and return summary. No wasted 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?

Despite no output schema, the description thoroughly explains the return value (versions, info, spec URLs, preferred version). Combined with annotations and simple schema, it is complete for the tool's purpose.

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

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

With 100% schema coverage, baseline is 3. The description reinforces the parameter meaning by giving examples and context ('exact APIs.guru name/key', 'from search_apis'), 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 retrieves the full directory entry for one API by its exact APIs.guru name/key. It distinguishes itself from sibling tools like search_apis by specifying that this is used after obtaining the exact name.

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 instructs to use this tool once the exact name is known from search_apis, and the goal is to fetch spec URLs. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. The description adds value by clarifying that the tool returns directory-wide statistics, providing scope context beyond the annotations.

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

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

The description is two sentences long, with the first sentence stating purpose and the second providing usage guidance. Every word earns its place; no redundancy or filler.

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

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

For a simple aggregate statistics tool with no output schema, the description is complete: it explains what data is returned (examples) and when to use it. No additional information is 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?

The tool has zero parameters, so schema coverage is 100%. The description adds meaning by listing example metric names (numAPIs, numEndpoints), helping the agent understand what the output contains. Baseline 4 is appropriate for no-parameter tools.

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

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

The description explicitly states the tool retrieves aggregate statistics for the entire APIs.guru directory, listing example metrics. This clearly communicates the verb 'get' and the resource 'aggregate statistics for the directory', distinguishing it from sibling tools that operate on specific APIs or providers.

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

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

The description advises using this tool for a high-level summary of directory coverage, which implies appropriate context. However, it does not explicitly mention when not to use it or compare with sibling tools like 'get_api' or 'search_apis', leaving room for improvement.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's additional details about return format and browsing context add value beyond what annotations provide. 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 two sentences, front-loaded with the core action, and every word serves a purpose. No fluff or repetition.

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

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

Given zero parameters, no output schema, and annotations fully covering safety, the description provides complete context: what it lists, example domains, return type, and use case. Nothing 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?

The schema has zero parameters and 100% schema coverage (vacuously), so no parameter documentation is needed. The description adds value by specifying the return shape ({ count, providers }), which is not in the schema.

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

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

The description clearly states it lists API providers (domains like 'googleapis.com', 'azure.com', 'amazonaws.com') tracked in the APIs.guru directory, and mentions the return structure { count, providers }. This is specific and distinguishes it from sibling tools like get_api or search_apis.

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

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

The description advises to 'use this to browse the directory by organization before drilling into a specific provider or API,' providing clear context on when to use it. It implies a workflow without explicitly mentioning alternatives, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, so the safety profile is well-covered. The description adds that subscriptions are 'active' and lists return fields, but does not significantly expand beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. No filler, front-loaded with the most important information.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. No gaps remain.

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

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

The input schema has 100% description coverage for the only parameter (include_inactive), so the schema already explains it. The description adds no additional parameter details, keeping the baseline at 3.

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 'List the caller's active subscriptions' and lists return fields (id, type, params, etc.). It clearly identifies the verb (list), resource (subscriptions), and scope (caller's active). It distinguishes from siblings like subscribe and unsubscribe.

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

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

The description provides explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly state when not to use, but the context is clear enough.

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

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

With all annotation hints false, the description carries the full transparency burden and does so well: it discloses rate limiting (5 per identifier per day), that it is free and doesn't count against quota, and that the team reads digests daily (signal affects roadmap). It also warns that misdirected feedback only delays the user. Minor gap: no statement of what happens after submission (e.g., no acknowledgement/return value), but the disclosed constraints are substantial.

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

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

The description is front-loaded with the core action and then logically flows through usage scenarios, exclusions, message guidance, and constraints. Every sentence adds value: scope definition, alternatives, directive on content, rate limit, and quota cost. It is appropriately sized for a tool with multiple usage modes and important boundaries, with zero waste.

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

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

For a feedback tool with 3 params, 2 required, a nested context object, and no output schema, the description fully covers purpose, when to use vs. not use, message formatting, rate limits, and quota impact. It even explains what the team does with the feedback. There are no significant gaps that would prevent an agent from correctly invoking the tool.

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

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

Schema coverage is 100% with rich descriptions for every parameter, including enum meanings and examples for nested context fields. The description adds some guidance on how to phrase the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and ties type selection to use cases, but this is marginal relative to the schema. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

Opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes itself from sibling tools by specifying that feedback is for tools served by this Pipeworx connection only, and enumerates the exact scenarios (bug, feature/data_gap, praise). This makes the tool's unique purpose unmistakable.

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

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

Provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data... when a tool you wish existed... when something worked surprisingly well') and gives a clear exclusion: file feedback with other MCP servers for non-Pipeworx tools. Also offers a fallback heuristic ('Not sure? 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 provide readOnly, idempotent, openWorld hints. Description adds value by specifying data source (CF analytics-engine), PII-free content, and cache behavior (5min-1h). 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 concise sentences with no waste: first sentence states purpose, followed by bullet-style use cases, then data source and cache details. Well-organized and 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?

For a simple, read-only tool with one parameter and no output schema, the description fully covers purpose, use cases, data provenance, and caching. No gaps remain.

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

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

Schema has one parameter with enum and description. Description adds meaning by explaining the behavior difference between windows (hot vs steady-state), which the schema's description does not explicitly state.

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

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

Description clearly states it returns top tools, packs, and call volume over a window, distinguishing it from siblings like discover_tools or search_apis by focusing on trending usage rather than discovery or search.

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

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

Lists three explicit use cases (discovering hot sources, confirming canonical tool, aligning use cases) and explains window trade-offs, but does not explicitly exclude any scenario or name alternative 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 annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds extensive behavioral context: the output structure (opportunities array, partition_check details), internal logic (Jaccard similarity, placeholder filter, fill check against CLOB depth), and constraints (partition filter for placeholder slugs). No contradictions with annotations.

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

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

The description is relatively long but all sentences are informative and add value. It is front-loaded with the main purpose and usage modes. Could be slightly more concise, but for the complexity of the tool, it remains well-structured and readable.

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?

Without an output schema, the description fully explains the return format, including fields like 'opportunities[]' with sub-fields and the partition_check object. It also covers edge cases (placeholder filter, fill check) and references the sibling tool for custom sizing. Complete enough for the agent to understand and use the tool correctly.

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

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

Schema coverage is 100% but the description adds significant extra meaning: it explains what each mode does, provides examples of valid values (e.g., 'fed-decision-may-2026' for event, 'Fed rate decision' for topic), and recommends which to use. This goes well beyond the basic schema descriptions.

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

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

The description explicitly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes (no args, event, topic) with specific examples, making it easy for the agent to understand the tool's purpose and differentiate from siblings.

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

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

The description provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains the strengths of each mode, such as cross-event catching patterns single-event misses, and gives concrete examples of valid inputs.

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

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

The description extensively details internal logic (three model families, tradeable-edge knobs, caching behavior) beyond what annotations provide. Annotations indicate read-only, open-world, idempotent, and non-destructive—all consistent with the description, which adds significant behavioral disclosure.

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

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

The description is front-loaded with core purpose and structured into numbered families. While dense, every sentence adds information. Could be slightly more concise, but it is well-organized.

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

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

Despite lacking an output schema, the description fully details the response format (by_segment, fed_candidates, diagnostics) and explains complex filtering behavior. For a tool with 9 parameters and significant inner logic, it provides comprehensive guidance.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for several parameters (e.g., min_partition_leg_kelly explains why min_kelly doesn't partition, slippage_pp notes zero fees but bid/ask depth). This lifts the score above baseline.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using a specific verb and resource. It implies a use case ('what should I bet on today') but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides context (e.g., 'discover opportunities without paging hundreds of markets') but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are named, though the tool is positioned for a specific discovery purpose.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral details: history depth bounded by 60-day TTL, decay from daily closes not intraday, and response structure with tracked/expired/snapshot_dates. No contradictions.

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

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

The description is front-loaded with the key question and uses clear sections. While lengthy, every sentence adds value with no redundancy. Slightly verbose but well-structured.

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

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

Given no output schema, the description comprehensively explains all response fields (tracked, expired, snapshot_dates) and limitations (TTL, decay basis). It leaves no major gaps for a complex time-series 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?

With 100% schema coverage, the description adds default values (14 days, '1wk'), clamp range for days (2-30), and clarifies window's role. This enriches understanding beyond the schema's basic 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 'Edge persistence and decay telemetry' and answers a specific trading question ('how long has this edge existed and is it shrinking?'). It distinguishes from sibling tools like polymarket_edges by focusing on temporal 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 implies usage for temporal edge analysis and contrasts with raw snapshots, but it does not explicitly state when not to use or name alternatives. The context is clear but lacks explicit exclusion guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds substantial behavioral context: it walks the order book ladder, returns specific fields, and warns about risks of partial basket fills converting arb into unhedged positions. No contradiction with annotations.

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

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

The description is dense with information but front-loads the purpose and clearly separates modes with capitalization. It is efficient, though slightly lengthy; every sentence adds value. Could be slightly more structured with bullet points, but remains concise for the complexity.

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

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

Given the tool's complexity (4 parameters, no output schema), the description is fairly complete. It covers both modes, lists return fields, and warns about risks. Missing discussion of rate limits or authentication, but annotations cover read-only and idempotent nature, reducing the burden.

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

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

Schema description coverage is 100%, so baseline is 3. However, the description adds extra meaning: explains how size_usd is interpreted differently for buys vs sells and basket mode, the default logic for side in basket mode, and the distinction between single-market and basket. This goes beyond the schema descriptions.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes single-market and basket modes. It explicitly ties usage to sibling tools polymarket_arbitrage and polymarket_edges, providing specific 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 specifies 'REQUIRES one of market or event' and explains defaults and when to use each mode. It advises using this tool before acting on arb signals or trades above $500, but does not explicitly state exclusions beyond those mentioned.

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

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

The description discloses extensive behavioral traits beyond annotations: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and skipped cross type/subtype counters. It aligns with annotations (readOnlyHint, idempotentHint) and adds critical context about spread validity.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. Every sentence adds value, though slightly verbose given the complexity.

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

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

Despite no output schema, the description comprehensively explains response structure, edge cases (e.g., no arb exists when shapes differ), and safety fields. It provides sufficient context for an AI agent to select and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the two modes, providing example values for explicit parameters, and detailing response fields (leg-by-leg prices, top_spreads_pp, safety fields) beyond schema definitions.

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

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

The description explicitly states it computes the cross-venue spread between Kalshi and Polymarket for the same question, distinguishing it from sibling tools like polymarket_arbitrage. It details two modes (topic shortcuts and explicit tickers), providing a specific verb+resource.

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

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

The description explains when to use the tool (comparing same outcomes across venues) and includes safety fields that warn when spreads are meaningless (e.g., incompatible bet shapes, temporal misalignment). It notes that pre-mapped topics often return warnings, guiding 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so base is high. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the pairing with remember/forget. No contradiction.

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

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

Three sentences front-loading the main action, with no wasted words. Efficient and well-structured.

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

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

The tool is simple (1 optional param, read-only). The description covers retrieval, listing, scoping, and pairing with other tools. No output schema needed. Complete for the complexity level.

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 already describes key parameter. The description adds 'omit to list all keys' which repeats the schema, and it provides context about key's purpose. At baseline 3, it adds marginal extra meaning.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys if omitted. It explicitly distinguishes from siblings (remember, forget) and specifies the resource (memory keys).

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

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

The description explains when to use it (look up context stored earlier, avoid re-deriving) and mentions scoping by identifier. It pairs with remember/forget but does not explicitly state when not to use or provide alternatives, which is acceptable given the simplicity.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral context by explaining the effect of mark_read on future calls and that polling works fine, which goes beyond annotations.

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

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

The description is four sentences, front-loaded with the main action, and each sentence adds value without redundancy. It is well-structured and 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?

The description covers all parameters, explains return content, and provides an alternative access method. For a read-only polling tool with no output schema, it is contextually 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?

With 100% schema coverage, the description still adds meaningful context: examples for type ('sec_8k'), ISO timestamp for since, and the behavioral effect of mark_read and unread_only. This enhances the schema's parameter descriptions significantly.

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 'Pull fired events from your subscription feed' and specifies the resource as 'most recent alerts'. It distinguishes itself from sibling tools by focusing on alert retrieval from a persisted feed, which is unique among the listed siblings.

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

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

The description provides guidance on filtering by type and since, using mark_read, and mentions polling suitability. It also gives an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool compared to alternative tools.

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

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

Annotations already indicate safe, non-destructive, and idempotent behavior. The description adds valuable context about fan-out to multiple sources, fallback from GDELT to GNews, and soft-fail for USPTO.

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 slightly long but front-loaded with examples and each sentence adds value. It could be more concise, but the structure is effective.

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

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

Despite missing an output schema, the description explains the return structure (grouped changes, total count, citation URIs) and covers all aspects: input semantics, behavior, fallbacks, and alternative tool. Complete for a complex tool.

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

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

Schema coverage is 100%, and the description adds meaning by explaining accepted formats for 'since' (ISO date or relative shorthand with examples), the allowed 'type' value, and that 'value' can be ticker or CIK, with typical usage advice.

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

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

The description clearly identifies the tool as a change feed for a company, with specific verb 'change feed for a company', and distinguishes it from the sibling tool 'entity_profile' by stating that the latter should be used for static profiles.

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

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

The description provides numerous usage examples and explicitly advises when to use the alternative tool 'entity_profile' instead, offering clear guidance on when to use this tool for dynamic changes vs. static profiles.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds significant behavioral context beyond annotations: it discloses scoping by identifier, persistence for authenticated users vs 24-hour retention for anonymous sessions. There is 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: it opens with the main action, then usage guidance, then behavioral details. It is a medium-length paragraph with no wasted words. Slightly verbose but all sentences add 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?

The tool has no output schema, but the description covers the essential aspects: what it does, how data is stored, scoping, and persistence. It does not mention error handling or return values, but for a simple memory store, the description is 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% with clear parameter descriptions. The description does not add new parameter-level information beyond the schema examples. It provides context about what kind of values to store but not syntax or format details. Baseline is 3, and the description adds marginal value.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It specifies it is for storing key-value pairs that persist across sessions or within a conversation. It distinguishes itself from sibling tools like recall and forget by explicitly mentioning pairing with them.

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

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

The description provides clear usage guidance: 'Use when you discover something worth carrying forward...so you don't have to look it up again.' It also tells how to pair with recall and forget, offering explicit context of when to use and how it relates to alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that each call cascades through several lookup endpoints, which is a useful non-obvious behavior. It also discloses the return format and auto-disambiguation, adding context beyond 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 somewhat long but well-structured and front-loaded with purpose and usage. It uses a clear SUPPORTED TYPES layout and every sentence contributes value, though it could be slightly tightened without losing information.

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

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

Since there is no output schema, the description fully compensates by detailing the return fields for both entity types (ticker, CIK, company_name, RxCUI, ingredient, brand, citation URIs). It also covers input flexibility and composite behavior, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'value' parameter with concrete examples (AAPL, 0000320193, ozempic) and explains auto-disambiguation for company input, going beyond the schema's generic description. This adds meaningful semantic guidance for parameter values.

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

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

The description clearly identifies the tool's purpose with a specific verb ('resolve') and resource (user-spoken name to canonical identifier). It provides concrete query examples and explicitly states that other tools require this identifier, distinguishing it from sibling tools like entity_profile or search_within.

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

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

The description explicitly instructs to 'Use FIRST whenever you have a name but need an ID', providing clear when-to-use guidance. It also explains that using this tool replaces 2-3 manual lookups, and lists supported entity types with details on what they accept, making usage context unambiguous.

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 true, and destructiveHint false. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. It does not contradict annotations and provides useful behavioral 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?

Description is three sentences: purpose, mechanism, example/output. Front-loaded with the core action. Every sentence adds value without redundancy.

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

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

Despite no output schema, description outlines return (ranked list with score, confidence, signal density). It could elaborate on error handling or output format details, but given the tool's complexity and rich annotations, it is largely 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%, baseline 3. The description adds significant meaning: 'entities' first entry is 'subject' for narrative, 'context' is shared across probes, and it clarifies the entities array composition (brand + N competitors). This enhances understanding beyond the schema.

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

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

Description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from sibling tools like ai_visibility_check by emphasizing side-by-side 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?

Description explicitly calls out competitive AI-marketing audits as the use case and implies when to use (comparing multiple entities). It mentions using ai_visibility_check internally, hinting at alternatives for single-entity checks, but lacks explicit when-not-to-use guidance.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. No contradictions with annotations.

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

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

The description is fairly concise given the complexity of the tool. It is front-loaded with the purpose and key features. While it contains a lot of detail, every sentence contributes meaning. Slightly verbose but appropriately so.

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 that there is no output schema, the description fully explains the return structure: summary block, per-advisory details, links, and alternative versions. It also covers constraints (npm only v1) and partial failure behavior. Complete for a complex tool.

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

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

The input schema already provides descriptions for both parameters with 100% coverage. The description adds value by specifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest. This adds nuance beyond the schema.

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

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

The description clearly states the tool's purpose: performing a composite check for adding an npm package, covering license, advisories, bundle size, dependency count, and ESM/tree-shake support. It distinguishes itself from siblings by explicitly limiting to the npm ecosystem.

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

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

The description provides explicit usage context: questions like 'is X safe / popular / small' or 'what does adding lodash cost me'. It also specifies when not to use (non-npm ecosystems) and points to alternative (deps.dev:version).

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, openWorldHint=true, so the safety profile is well covered. The description adds useful behavioral detail beyond annotations: multi-word queries are matched word-by-word not as exact phrases, ranking prioritizes name matches over description matches. It also reveals the truncated-description and last-updated-date return behavior.

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

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

Compact, front-loaded description. First sentence states purpose immediately. Second sentence lists return fields efficiently. Third sentence gives usage directive. All sentences earn their place; no fluff. Slightly longer than strictly necessary due to detailed return-field list, but each item is informative.

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 search/discovery tool, the description is complete: covers what it searches, matching behavior, return fields, and how it connects to get_api. No output schema exists but the description enumerates all returned fields explicitly. The matching/ranking algorithm disclosure compensates well for lack of output schema details.

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 both parameters are documented in the schema. The description adds meaningful value beyond the schema: it explains the query matching algorithm in detail (word-by-word matching, ranking by word count and match location) and provides concrete examples. The limit parameter defaults to 20, which is stated in schema; the description reinforces search semantics.

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

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

Very specific verb+resource: "Search the APIs.guru directory of 2,500+ public APIs by free-text query." Clearly states what it searches, what it matches against (name/key, title, description, categories), and what it returns. Clearly distinguishes from siblings like get_api (which retrieves a specific API) by noting it outputs the exact name to pass to get_api.

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 explicitly states when to use: "Use this to discover which public APIs exist for a given domain... and to get the exact name to pass to get_api." While it doesn't explicitly name alternatives or say when NOT to use it, it clearly demarcates this tool's role relative to get_api, giving strong usage context.

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

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

Annotations already mark it as read-only, open-world, idempotent, non-destructive. The description adds technical details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag. This adds significant behavioral context beyond the annotations.

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

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

The description is about 4 sentences, efficiently front-loaded with key purpose and usage. Every sentence adds value—no fluff, no repetition. Ideal conciseness 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?

No output schema, but the description mentions return format (top-N passages with character offsets and similarity scores). This is sufficient for an agent to understand what to expect. Could be more explicit about the exact structure, but overall complete 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 coverage is 100% (3 params described). The description adds practical details not in the schema: max ~200K chars for text, default limit of 5, and illustrative query examples. This enhances understanding without being redundant.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verbs like 'search inside' and providing concrete examples (SEC 10-K, article). It distinguishes from sibling tools like search_apis (general search) and ask_pipeworx_grounded (grounded over passages).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded. This provides clear when-to-use guidance and references alternative 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?

The description discloses behavioral traits well beyond annotations: it explains that subscriptions require OAuth, delivery channels (feed always on, optional email/sms/webhook with constraints like SMS verification, 10/day cap, webhook auto-disable after 10 failures), and that webhook secret is returned once. 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 appropriately detailed yet well-structured. It front-loads the core purpose and output, then systematically covers types, parameters, and delivery options. Every sentence adds value without redundancy, making it easy to scan.

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

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

Given the tool's complexity (multiple subscription types, delivery channels, authentication requirements), the description covers all necessary aspects: purpose, output, required auth, type-specific parameters, delivery constraints, and side effects. No output schema exists, but the description states it returns an ID, which suffices.

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?

Despite 100% schema coverage, the description adds significant meaning: it explains the semantics of type-specific params (e.g., item codes for sec_8k, topic for polymarket_edge) and delivery options (e.g., SMS verification requirement, webhook HMAC signing). This goes well beyond the schema descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe by specifying the action and output.

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 prerequisites (Pipeworx OAuth account) and detailed type-specific parameter guidance. However, it lacks explicit instructions on when not to use this tool versus alternatives like list_subscriptions or unsubscribe, and doesn't mention potential conflicts with existing subscriptions.

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, openWorldHint, and non-destructive. The description adds value by specifying the exact output format (category-bucketed example questions with tool+argument shapes) and that it serves as an onboarding tool. It does not contradict annotations.

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

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

The description is well-structured: it starts with common query phrases, states the purpose, then explains the output and usage. It is informative without being verbose, though it could be trimmed slightly. Every sentence adds value.

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

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

Given the tool has one optional parameter and no output schema, the description fully covers what the tool does, what it returns (category-bucketed example questions with tool+argument shapes), and how to use it (no args vs. topic filter). It also provides the list of categories. This is complete for an onboarding tool.

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

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

Schema coverage is 100% with a clear description for the topic parameter. The description adds extra context: explains that omitting topic gives a cross-category spread, lists example values (finance, pharma, etc.), and indicates it's optional. This goes beyond the schema's baseline, justifying a 4.

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

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

The description clearly states the tool returns category-bucketed example questions to help users know what to ask. It lists specific categories and indicates it's the onboarding entry point. It distinguishes from siblings like ask_pipeworx by explicitly saying 'Use this FIRST' and mentions it teaches how to call meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It provides context for when to use it and offers optional topic filtering. However, it does not explicitly state when not to use alternative tools like ask_pipeworx, so it lacks full exclusion guidance.

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

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

Discloses deactivation (not deletion) and ownership enforcement, adding context beyond annotations (readOnlyHint=false, destructiveHint=false).

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

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

Two concise sentences, action first, 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?

Fully covers purpose, behavior, and constraints for a simple one-param tool with 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?

Only one parameter with full schema coverage; description confirms it's by id but adds no new 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?

Clear verb 'cancel' with specific resource 'subscription by id'. Distinct from siblings subscribe and list_subscriptions.

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

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

States ownership enforcement (cannot cancel others), and explains deactivation vs deletion with reference to recent_alerts for historical events.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description goes far beyond, explaining the internal dual-path logic (SEC EDGAR for company-financial claims, grounded pipeline for others), mention of exact percent-delta math, and the specific verdict types returned. It also discloses that it adds pipeworx:// citations and replaces multiple sequential calls. No contradictions with annotations.

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

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

The description is a bit long (4-5 sentences) but each sentence adds distinct and valuable information. It is front-loaded with example inputs and clearly structured. While not maximally concise, the length is justified by the tool's complexity and the need to explain two processing paths.

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

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

Given no output schema, the description adequately describes return values (verdict, actual value with citation, reasoning). It covers both processing paths comprehensively, explains the tolerance logic, and mentions the citation format. The description is complete enough for an agent to understand input, behavior, and output.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds practical guidance beyond schema: for tolerance_pct, it explains that it overrides the default implied by wording and suggests values 1–2 for hallucination detection. This significantly aids correct usage.

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 concrete natural-language examples ("Is it true that…", "fact check"), then explicitly states it verifies factual claims against authoritative sources. It distinguishes two processing paths (structured SEC EDGAR for financial claims vs. grounded pipeline for others), making the tool's specific role very clear. This distinguishes it from sibling tools like deep_research or ask_pipeworx, which are more general.

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

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

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct." It also hints at efficiency by claiming it replaces 4–6 sequential calls. However, it does not explicitly mention when NOT to use it or suggest alternative tools for non-verification tasks. Still, the guidance is strong and context-aware.

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