Themeparks

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the return format (per-model {score, confidence, signals, raw_response} + combined view), cost implications (free default, BYO key for Anthropic), and the fact that it probes external LLMs. 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?

Description is four sentences, front-loaded with the core action and output. Each sentence adds essential information without redundancy or verbosity.

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

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

No output schema exists, so the description must explain return values, which it does clearly. All four parameters are described with sufficient context. Minor gap: does not mention error handling or rate limits, but is otherwise 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: provides example values for entity ('Pipeworx'), clarifies default model for models, explains necessity of _apiKey for Anthropic, and gives disambiguation example for context. This extra context elevates 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 clearly states the action ('probe one or more LLMs', 'score visibility'), specifies the resource ('business / brand / product / topic'), and provides a 0-100 score range. It distinguishes itself from siblings by being unique in function; no other sibling tool performs AI visibility checks.

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 examples ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains default model behavior and how to include Anthropic with an API key. However, it lacks explicit when-not-to-use or mention of alternative tools, though no siblings overlap.

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, and non-destructive behavior. The description adds valuable context beyond that: it routes queries, fills arguments, returns structured answers with stable citation URIs, and is 'one fast call'. It doesn't contradict the annotations.

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

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

The description is long but well-structured: starts with a strong directive, explains scope, provides examples, and ends with alternatives. Every sentence adds value, though it could be tightened slightly 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?

For a complex meta-tool with no output schema, the description is remarkably complete. It covers when to use, when not to use, alternatives, examples, and even notes that it works on every tier. The only minor gap is lack of error/rate-limit info, but that's not critical here.

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

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

Schema coverage is 100% with detailed aliases and descriptions for the question parameter. The description doesn't explain parameter syntax beyond what the schema provides, but it does give many example queries that illustrate expected input. This meets the baseline but doesn't exceed it 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 what the tool does: routes questions to one of 5,558 tools across 1461 sources and returns structured answers with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so the purpose is unambiguous.

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

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

Extremely explicit usage guidance: 'PREFER OVER WEB SEARCH' for specific domains, 'START HERE' as the default entry point, and concrete instructions when to step up to ask_pipeworx_grounded or deep_research. Also handles the breaking-news edge case with live news routing.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. The description adds valuable context: it is a full working router, not a fallback, and currently matches ask_pipeworx exactly since no candidate is active. This clarifies the experimental state and avoids misconceptions about limited 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 four sentences long and front-loads the core identity ('Beta version of ask_pipeworx'). Each sentence carries useful information (candidate testing, current state, usage, and safety), though it could be slightly tighter without losing meaning.

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

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

For a complex router tool with no output schema, the description compensates by noting the response shape is identical to ask_pipeworx and that it is a fully functional router. The relationship to the stable sibling is clearly established, making the tool understandable in context.

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

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

The input schema has 100% coverage; all six parameters are aliases for 'question' with descriptions. The description adds no parameter-specific meaning besides referencing 'same arguments' as ask_pipeworx, which is adequate. Baseline of 3 applies given the high schema coverage.

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

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

The description clearly identifies the tool as a 'Beta version of ask_pipeworx' and a 'universal router' with the same scope (5,558 tools). It distinguishes from the sibling ask_pipeworx by noting it is the experimental edge with candidate routing improvements.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing', providing a clear when-to-use condition. It implies stable alternatives (ask_pipeworx) by contrasting the beta with the stable router, though it doesn't explicitly say 'use the stable version for production needs'.

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

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

Goes well beyond annotations by disclosing the internal routing mechanism, the strict extraction from tool results, the precise shape of success and refusal responses (including refusal_reason enum), and the lack of invention. No contradiction with annotations (readOnlyHint true, etc.), and it adds rich behavioral context.

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

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

The description is dense and well-organized: purpose, mechanism, output format, usage guidance, and cost trade-off. Every sentence adds value, and the structure flows logically from what it does to when to use it, with 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?

For a tool with no output schema and potentially complex refusal logic, the description fully specifies return values, refusal reasons, and usage context. It provides everything an agent needs to select and invoke this tool correctly, including edge cases (data_truncated, tool_error).

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

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

The schema already has 100% coverage with descriptions for all aliases and the main 'question' field. The description adds no parameter-specific detail, but this is acceptable because the schema fully documents that all parameters are aliases for the question. 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 states this is a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts the answer') and resource. It differentiates from sibling ask_pipeworx by emphasizing evidence-based extraction and refusal behavior, making the tool's distinct 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 provides when to use ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'), while naming the alternative. Also notes the cost trade-off (one extra LLM call), giving clear decision criteria.

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

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

With annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds extensive behavioral context: safety mechanisms (low-confidence short-circuit, closed market handling), resolution-rule risk, cancellation rule parsing, response shapes, and edge cases like wide spreads. It significantly enriches the agent's understanding of tool behavior.

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

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

The description is front-loaded with purpose and usage, then systematically details classifiers, fan-out examples, response shapes, and safety. While lengthy, every sentence adds essential information. It could be slightly more concise by grouping related details, but remains 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?

The tool is complex (multiple classifiers, fan-out to various sources, detailed response shapes). The description covers all essential aspects: input formats, behavior, output structure, edge cases, and safety. Since there is no output schema, the description fully compensates by explaining return values and fields like resolver contract and parent_event.

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 valuable context: 'market' accepts slug, URL, or question text; 'depth' and 'include_raw' are explained with practical recommendations. This goes 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 uses a specific verb ('Research') and resource ('a Polymarket bet by pulling the relevant Pipeworx data'), clearly distinguishing the tool from siblings like polymarket_edges or validate_claim. It states the tool's core function in the first sentence and provides concrete usage examples.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also explains classifiers and fan-out patterns. However, it does not explicitly state when not to use it or mention alternative tools, which would clarify boundaries further.

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

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

Description adds significant behavioral context beyond annotations: off-calendar fiscal year handling, specific metrics pulled, sorting behavior, and output format with citation URIs. Annotations already indicate read-only, idempotent, open-world, non-destructive; description reinforces and 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?

Concise yet comprehensive: trigger phrases first, then core purpose, type-specific details, sorting, output references. No wasted words.

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

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

Covers all necessary aspects for an agent to decide and invoke correctly: inputs, data sources, accuracy notes, output shape (paired data + URIs). No gaps despite lack of output schema.

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

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

Schema already defines parameters with enums and array constraints (100% coverage). Description adds examples (e.g., tickers, drug names) and clarifies meaning of values for each type, which is helpful but not essential given schema completeness.

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

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

Description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases. It distinguishes from siblings by explicitly preferring over sequential single-entity lookups.

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

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

Provides explicit guidance on when to use (comparisons, rankings) and when not (sequential lookups). Also explains type-specific use cases and data sources.

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

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

The description goes well beyond the provided annotations (readOnlyHint, idempotentHint, etc.) by disclosing auth requirements, latency expectations (15-60s, up to 90s), the return packet structure (verbatim evidence, confidence, source, fetched_at, citation_uri), the behavior of gaps[] and contradictions[], and the fact that records are semantically excerpted. It also states it 'never invented' data, adding trust. 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 every sentence serves a purpose, providing critical context about prerequisites, use cases, behavior, and output. It is front-loaded with the account requirement. While a bit dense, the structure is logical and the length is justified by the tool's complexity.

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

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

Despite having no output schema, the description thoroughly explains what the user can expect: findings packet with evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop field, and semantic excerpting. It covers auth, latency, and alternative tools, making it complete for a complex research tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant value by explaining the meaning and trade-offs of the 'depth' parameter (quick=3, standard=5, thorough=8) with additional behaviors like gap recovery and contradiction scans. It also clarifies that 'question' can be broad/multi-part. This enriches 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 function: 'Grounded multi-source research across Pipeworx's 1461 STRUCTURED data sources' in one call, with a specific verb ('researches'/'decomposes') and explicit resource ('Pipeworx's structured data sources'). It distinguishes this from sibling tools by noting it is NOT open-web search and routes to 5,558 tools, and it contrasts with ask_pipeworx for single lookups.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not-to-use: 'For a single lookup use ask_pipeworx' and for breaking/current-news 'prefer ask_pipeworx'. It also mentions account requirements and the alternative if not signed in. This is thorough and actionable.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds that results include full schemas and are ready to call, reinforcing safe, non-destructive behavior without contradiction.

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

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

The description is front-loaded with purpose and usage, though the list of domains is lengthy. It remains efficient and focused, with minimal redundancy.

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

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

Given no output schema, the description adequately describes return format (top-N tools with schemas). It covers the core use case and invocation order, missing only error handling or edge cases.

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

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

Schema coverage is 100% with descriptions for each parameter. The description supplements with alias information and explains the 'limit' parameter's defaults, 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 'Find tools by describing the data or task' and lists numerous domains, making the tool's purpose explicit and distinct from siblings which focus on specific tasks.

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

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

The description explicitly advises 'Call this FIRST when you have many tools available' and enumerates scenarios like 'browse, search, look up', providing clear usage context but no explicit exclusions.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it fans out across multiple data sources, details the exact return fields, and mentions the patent API sunset (May 2025) with graceful degradation. There is no contradiction.

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

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

The description is somewhat lengthy but well-structured and front-loaded with example queries. Every sentence adds value, covering purpose, sources, return fields, and limitations. While it could be slightly more concise, it remains clear and efficient given the tool's complexity.

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

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

Given the lack of an output schema, the description compensates by enumerating all return components (cik, recent_filings with URIs, fundamentals sorted, patents with sunset note, news via fallback, LEI). It also mentions input constraints (ticker/CIK, no names) and the parallel call behavior. This is comprehensive 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% with descriptions for both parameters. The description adds further meaning beyond the schema: explains that 'value' accepts ticker or zero-padded CIK, that names are unsupported, provides examples ('AAPL', '0000320193'), and clarifies the 'type' parameter (only company supported). 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 clearly states the tool's purpose: given a ticker or CIK, returns a comprehensive cross-source profile of a US public company. It uses specific verbs and resources (e.g., 'full cross-source profile', 'fans out across SEC EDGAR, XBRL...') and distinguishes itself from sibling tools like resolve_entity by noting that names are not supported.

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

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

The description explicitly advises 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use: 'names not supported (use resolve_entity first if you only have a name).' This provides clear guidance on when to use this tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true, so the description adds value by specifying 'clear sensitive data' context, but does not add much beyond that.

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

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

Two efficient sentences, front-loaded purpose, no waste; every sentence earns its place.

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

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

For a simple delete tool with one parameter and strong annotations, the description adequately covers purpose and usage, though missing potential edge cases (e.g., what if key doesn't exist) is minor.

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 extra meaning beyond the schema's 'Memory key to delete'. Baseline of 3 applies.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource, and distinguishes itself from sibling tools like 'remember' and 'recall'.

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

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

Explicitly states when to use ('context is stale, task is done, or clear sensitive data') and pairs with related tools, providing clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, establishing a safe, idempotent operation. The description adds valuable behavioral details: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. 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 three sentences, each serving a purpose: stating the action, explaining the process, and listing use cases. No wasted words; front-loaded with the core function.

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 nested objects, no output schema), the description covers all necessary context: input (URL), optional param, process (fetch, extract, emit), and output format (text blob). The annotations further fill safety and idempotency context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reiterates the parameters (url, max_links) but does not add significant new semantics beyond what the schema provides. It confirms default and max values for max_links, but that is already in the schema description.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the resource (URL) and action (generate), and provides concrete use cases, making it highly distinct from sibling 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 lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it does not provide negative examples or alternatives, the given context is sufficient for an agent to understand when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds value by specifying the exact fields returned and the types of entities covered, providing 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?

Single sentence, no redundant information, front-loaded with key details. Highly concise.

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 is adequately complete. It could mention error handling or output format, but the core functionality is clear.

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

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

Schema description coverage is 100% with a clear description of entity_id. The tool description does not add new semantic information for the parameter beyond what the schema already provides.

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

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

Description clearly states it returns metadata for theme park entities and lists specific fields (name, type, location, timezone, parent ids) and entity types. It distinguishes from siblings like get_wait_times but could be more explicit about how it differs from entity_profile or resolve_entity.

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

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

No explicit guidance on when to use this tool versus alternatives. The schema description hints at where to get entity IDs but does not provide usage context or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool returns data 'over the coming weeks', which provides temporal context beyond annotations. No contradictions.

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

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

Two sentences with no redundant wording. The description is front-loaded with the resource and provides a clear instruction. Every word adds value.

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

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

For a simple read-only tool with one parameter and no output schema, the description explains what the tool returns (hours over weeks) and how to get the entity_id. It is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100% and the description restates the parameter guidance ('Pass a PARK entity_id from list_destinations') without adding new detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('get' is implied by title) and resource: 'Park operating hours — opening and closing times for a theme park over the coming weeks'. This distinguishes it from sibling tools like 'get_wait_times' and 'list_destinations'.

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 a clear usage instruction: 'Pass a PARK entity_id from list_destinations'. This implies a prerequisite to call list_destinations first. It does not explicitly state when not to use it, but the context is sufficient for an agent to infer appropriate usage.

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

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

Annotations already indicate this is a read-only, idempotent, open-world operation with no destructive behavior. The description adds behavioral details: what data is returned (standby and single-rider queue minutes, operating status) and that it covers every attraction in a park, which adds value beyond annotations.

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

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

The description is concise and well-structured: two sentences that first explain the purpose and then provide usage instructions. No extraneous information, front-loaded with key details.

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

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

Given the absence of an output schema, the description compensates by explaining what the tool returns (standby and single-rider queue minutes, operating status). It is adequate for a single-parameter tool, though a more detailed example of the output could improve completeness. Context signals indicate low complexity, so the description is nearly complete.

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

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

Schema coverage is 100%, with the schema providing a description for entity_id ('A PARK entity id from list_destinations.'). The description reinforces this same information but does not add additional semantic detail. Baseline 3 is appropriate since the schema already covers the parameter meaning adequately.

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

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

The description clearly states that it returns live theme park wait times, including standby and single-rider queue minutes and operating status for every attraction in a park. It specifies the resource (live wait times) and the action (get/return), and differentiates from siblings by focusing on wait times specifically.

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

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

The description provides clear context: use this tool to get current wait times for a park, and requires passing a PARK entity_id from list_destinations. However, it does not explicitly state when not to use this tool or mention alternatives, which would improve 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 cover safety profile (readOnly, idempotent). Description adds workflow context (discovery of park IDs). No contradictions.

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

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

Two sentences, no wasted words. Front-loaded with purpose, followed by actionable 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?

Complete for a parameterless, read-only listing tool with good annotations. Tells agent what it returns and how to use the 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?

No parameters in schema (coverage 100%), so baseline 4. Description doesn't need to add parameter info.

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 lists theme park destinations and parks, with specific examples. Differentiates from siblings by describing the workflow of using this tool first to get entity IDs for other tools.

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

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

Explicitly states when to use (first step) and provides next steps (feed entity ID to other tools). Missing explicit 'when not to use' or alternative tools, but the workflow guidance is strong.

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

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

Annotations already indicate read-only, idempotent behavior. Description adds details on returned fields and default filtering (active subscriptions). No contradictions.

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

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

Two sentences: first states purpose and output, second gives usage guidance. No fluff, 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 full annotations and schema coverage, description adequately explains behavior, return fields, and usage context. No gaps.

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

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

Schema coverage is 100% for the single parameter; description does not add further meaning but is consistent with schema. Baseline 3 is appropriate.

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

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

Description clearly states verb 'list' and resource 'subscriptions' for the caller, and specifies returned fields. 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?

Provides explicit use cases: 'review what you're monitoring' and 'find an id to cancel'. Does not explicitly state when not to use, but context is clear.

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

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

Since all annotation hints are false, the description carries the full burden of disclosing behavior. It reveals rate limiting ('Rate-limited to 5 per identifier per day'), the fact that filing returns a claim_token, that it is free and doesn't count against quota, and that the team reads digests daily. This goes well beyond the minimal safety info annotations provide.

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

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

The description is lengthy but every sentence serves a purpose: usage, exclusions, token mechanics, rate limits, and quota impact. It is front-loaded with the core action and use cases, though the sentence about 'Pipeworx tool names are the ones this connection lists' is slightly redundant given the exclusion earlier.

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

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

With no output schema, the description explains all post-invocation behavior: returning a claim_token, how to check status later, rate limiting, and quota exemption. It fully covers the tool's lifecycle and boundaries, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage guidance not in the schema, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and clarifies the claim_token flow for checking status later. This adds value beyond the schema's dry 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb-resource phrase. It clearly distinguishes itself from siblings like ask_pipeworx by framing itself as feedback submission about Pipeworx tools, not a query tool.

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

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

The description explicitly states when to use it: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with the other server for different MCP servers.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: data source (CF analytics-engine), privacy assurance (no PII, only counts), caching behavior (5min-1h depending on window). This fully meets the behavioral transparency burden.

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 with zero waste. It is front-loaded with the primary output, followed by bulleted use cases, then technical details. Every sentence contributes meaningfully.

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 optional parameter and no output schema, the description is complete. It explains the output, use cases, data source, privacy, and caching. No gaps remain given the tool's complexity and the richness of annotations.

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

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

The schema covers the single parameter 'window' with 100% description coverage. The description adds semantic value by explaining the effect of different window lengths: shorter windows surface what's hot right now, longer show steady-state demand. This goes beyond the schema's basic description and aids the agent in choosing wisely.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a configurable time window. The verb 'returns' and the resource context ('what other AI agents are calling') are specific, and the tool is well-distinguished from siblings focused on querying (e.g., 'ask_pipeworx') or other analytics.

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

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

Three explicit use cases are provided: discovering hot data sources, confirming canonical tools, and checking use-case alignment. While no explicit 'when not to use' is stated, the context makes it clear that this tool is for trending insight rather than factual queries, which suffices given the sibling list.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: fill check against live CLOB depth, partition filter for placeholder slugs, semantic anchor for cross-event pairs, and when realizable edge is non-positive do not trade.

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

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

The description is thorough but slightly verbose; it could be trimmed without losing critical information. However, it is well-structured with clear sections for each mode and additional notes.

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 the response structure, including opportunities array fields, partition_check object, and fill check details. Covers edge cases and references related tools.

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

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

Schema coverage is 100%, but description adds significant meaning: examples of slugs, accepted URLs, modes triggered, and details like 'Full Polymarket URLs also accepted'. It clearly defines what each parameter does beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes from siblings like polymarket_edges by specifying the exact methodology and modes (trending, event, topic).

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

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

Explicit guidance on when to use each parameter: no args for trending scan, event for per-event partition check, topic for cross-event scan. Also explains when not to trade (fill check) and directs to polymarket_fill_risk for custom sizing.

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

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

The description provides extensive behavioral details beyond the annotations: caching (1h at KV level), response structure (by_segment segments), edge calculation methods, Kelly sizing, tradeable-edge knobs, and diagnostics. All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent with a read-only scan tool. No contradictions.

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

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

The description is well-structured with clear sections (model families, knobs, response), but it is quite long. It is front-loaded with the purpose, and every major concept is explained. Could be slightly more concise, but the detailed structure aids understanding for an AI agent.

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

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

Despite having no output schema, the description thoroughly explains the return format (by_segment, top-level fields, diagnostics) and all relevant concepts (edge calculation, Kelly, caching). Given the tool's complexity (9 parameters, three segments), the description is completely adequate for an AI agent to use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters with descriptions. The main description adds context for how the knobs relate to filtering (e.g., 'Tradeable-edge filter') but does not provide substantial new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and resources ('top Polymarket markets', 'Pipeworx data'), and the purpose is well distinguished from sibling tools like polymarket_arbitrage and 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 explicitly includes the use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It provides context on when to use it. However, it does not explicitly state when not to use it or name alternatives, though the scope is clear given the sibling tools.

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

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

Annotations already indicate read-only and idempotent. The description adds beyond: explains snapshot-based data, 60-day TTL, limitation of daily closes (not intraday), and structure of response fields like first_seen, trend, decay_pp_per_day. No contradictions.

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

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

The description is somewhat long but efficiently structured: starts with core purpose, then detailed response format, then limits. Almost every sentence adds value, though minor redundancy could be trimmed.

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

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

Despite no output schema, the description fully explains return structure (tracked[], expired[], snapshot_dates[]) with field semantics. Parameters are thoroughly described. Covers all necessary details for correct usage.

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

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

Schema coverage is 100%, baseline 3. The description adds context: explains 'days' as lookback with default/max beyond schema constraints, and describes 'window' as snapshot family with examples. This provides useful additional 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 it provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity. It distinguishes from sibling tool 'polymarket_edges' by focusing on historical trends rather than current values.

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

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

The description implies when to use (analyzing edge history/decay) and contrasts fresh vs. aged edges. However, it lacks explicit instructions on when not to use or direct alternatives beyond the implied sibling tool.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds details: walking the ladder, returning fields (top_of_book, vwap_fill_price, etc.), and warns about forced directional 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?

Dense but front-loaded with purpose and requirements. Every sentence adds value, though it could be slightly more concise. Good structure with clear sections for single-market and basket modes.

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 description thoroughly explains return fields. Covers two modes, edge cases (thin legs, forced directional risk), and usage context. 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%, so baseline 3. The description adds context: explains single-market vs basket modes, defaults for side and size_usd, interpretation of size_usd for basket (settlement notional). Adds meaningful 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 function as a realizable-vs-theoretical edge check against live order-book depth. It distinguishes between single-market and basket modes, and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why—theoretical overround on thin books is not capturable and partial fills convert arb to directional risk.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds crucial details: compatibility_warning scenarios, temporal_alignment, skipped_cross_types, and the real-world rarity of tradeable spreads. No contradictions with annotations.

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

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

The description is lengthy but well-structured with bold headings and sequential explanation of modes, response, safety/alignment fields. Every sentence adds context; minor verbosity is justified by tool complexity.

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

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

With no output schema, the description must self-contain the return shape. It covers leg-by-leg prices, top_spreads_pp, and safety fields, but lacks explicit JSON structure or all field names. Sufficient for an agent, but not exhaustive.

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 dramatically expands meaning: lists the 10 pre-mapped macro shortcuts, explains the override behavior, and gives example tickers. This adds significant 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 it computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, and distinguishes from siblings like polymarket_arbitrage by specifying the two-venue scope. The verb 'compute spread' and resource 'Kalshi and Polymarket events' are explicitly defined.

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 two modes (topic vs. explicit tickers) and warns that many pre-mapped topics return compatibility warnings, setting expectations. However, it does not directly contrast with alternative tools like polymarket_arbitrage, leaving some inference to the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' 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, efficient, and front-loaded with the main action. Every sentence provides essential information without redundancy.

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

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

Given no output schema, the description explains the expected return (value or list of keys). It also covers scoping and pairing with sibling tools, making it fully informative.

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 description for the 'key' parameter. The description repeats the schema's info about omitting the key to list all keys, adding minimal additional 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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It distinguishes from sibling tools like remember and forget by specifying the retrieval and listing functions.

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

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

The description provides clear guidance on when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget, but doesn't explicitly state when not to use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context about the returned fields (source, citation_uri, raw payload) and the effect of mark_read flagging events as read. However, it does not fully contradict annotations, but the mark_read behavior might imply a state change, creating a slight inconsistency.

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

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

The description is concise at four sentences, each adding essential information. It front-loads the purpose and immediately describes return fields. There is no redundancy or unnecessary detail.

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

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

With no output schema, the description adequately explains the return structure (source, citation_uri, payload). It covers key parameters and usage scenarios. However, it could mention default values or error handling, but overall it is complete for a filtered-list tool.

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

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

Input schema covers all 5 parameters with descriptions (100% coverage). The description adds value by providing an example for 'type' ('sec_8k') and clarifying that 'since' expects an ISO timestamp. It also explains the behavior of 'mark_read' beyond the schema. This is above the baseline of 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 clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed) and the action (pull recent alerts). The description distinguishes it from siblings like 'list_subscriptions' or 'recent_changes' by focusing on fired events from the feed.

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 retrieving recent subscription alerts and mentions polling is acceptable, but it does not explicitly state when to use this tool versus alternatives like 'list_subscriptions' or 'recent_changes'. There is no direct comparison or 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?

The description details the tool's behavior beyond the annotations: it fans out to multiple sources (SEC EDGAR, GDELT→GNews, USPTO), explains the fallback strategy, accepts ISO dates or relative shorthand, and returns structured changes with citation URIs. The annotations already indicate read-only and idempotent, and the description adds context on source selection and error handling.

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

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

The description is a single paragraph but front-loaded with example queries and ends with a clear alternative. It efficiently conveys all necessary information without extraneous text. A more structured format (e.g., bullet points) could improve readability, but it is not overly long.

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 there is no output schema, the description adequately explains the return structure: changes grouped by source, total_changes count, and pipeworx:// citation URIs. It also notes the patents soft-failure. The tool covers three complex sources and the description addresses all aspects.

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

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

The input schema has 100% description coverage, but the tool description adds significant meaning: it explains that 'type' only supports 'company', gives examples for 'since' (ISO date and relative shorthand like '7d', '30d', '1y'), and explains that 'value' can be a ticker or zero-padded CIK. 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 opens with example queries ('What's new with X', 'latest on Y') that directly convey the tool's purpose. It clearly states it returns a change feed for a company covering SEC filings, news, and patents, and distinguishes itself from the sibling tool 'entity_profile' which provides 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 explicitly tells when to use this tool (for recent changes) and when not to ('Use entity_profile instead when you want the static profile'). It also explains the fallback behavior between GDELT and GNews, and specifies that patents may soft-fail. This provides clear 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 indicate idempotentHint=true and non-destructive. Description adds key behavioral traits: key-value storage scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous. 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?

Description is well-structured and front-loaded with purpose, but slightly verbose. Could be tightened without losing meaning. Still mostly efficient.

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

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

Given the simplicity of the tool (2 required params, no output schema), the description fully covers purpose, usage, storage details, and persistence. 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 100% coverage with descriptions for both key and value. The description adds example values but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples like tickers, addresses, preferences. It also distinguishes from sibling tools recall and forget.

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

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

Explicitly states when to use: when discovering something worth carrying forward. Provides context on scoping and persistence, and mentions pairing with recall and forget for retrieval and deletion.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds substantial behavioral context: graceful degradation of LEI/FIGI enrichment when sources are unavailable, explicit reporting of unresolved identifiers under 'unresolved', and internal cascading through multiple endpoints. These are value-add behavioral details 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 long but information-dense and well-structured: it starts with query examples, states the primary use, then details supported types and edge cases. Every sentence contributes value, though some details could be streamlined without loss of clarity.

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

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

Despite no output schema, the description fully covers what the tool returns (canonical identifiers with source labels, unresolved items explicitly listed, RxCUI citations), and explains fallback behavior. It is complete for a complex tool with internal cascading and multiple data sources.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the parameters by providing concrete examples (AAPL, 0000320193, ozempic) and explaining nuanced behaviors like ISIN-to-LEI mapping for non-US issuers. This goes beyond the schema's simple type/key 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 uses a specific verb ('resolve') and clearly identifies the resource: user-spoken names to canonical identifiers. It distinguishes itself from siblings by stating it provides identifiers required by other tools and replaces 2-3 manual lookups, making its unique role 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?

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' The description also provides query examples, supported types, and clarifies input formats (ticker, CIK, ISIN, brand/generic name). This is strong usage direction without needing explicit exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds behavioral details beyond annotations, such as that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides valuable context without contradicting annotations.

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

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

The description is concise with two short paragraphs. The first sentence provides a clear summary. Every sentence adds value, and there is no redundancy or fluff. The structure is logical: overview, process, use case, and output.

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, batch operation), the description comprehensively covers input, process, and output. There is no output schema, so the description adequately describes the return format (ranked list with score, confidence, signal density per entity). All essential behavioral aspects are covered.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds meaning by explaining that 'entities' first entry is the subject, and 'context' disambiguates common names. It also clarifies the 'models' parameter's default and the dependency on _apiKey. This adds value beyond the schema.

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

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

The description uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces' to clearly state the tool's function. It distinguishes itself from sibling tools like ai_visibility_check and compare_entities by explicitly describing the multi-entity comparison and ranking aspect. The example use case 'competitive AI-marketing audits' further clarifies its purpose.

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

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

The description provides clear usage context: 'useful for competitive AI-marketing audits' and an example question. It implicitly excludes single-entity checks (which would use ai_visibility_check) but does not explicitly state when not to use or list prerequisites like needing an API key for certain models. The note about the first entity being the 'subject' is helpful.

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

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

Description adds value beyond annotations by disclosing partial failure behavior (bundlephobia first measurement can take 5-30s, sources_failed lists timeouts), graceful degradation, and that it's a composite fan-out call.

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?

Front-loaded with core purpose and usage, every sentence provides essential information, no redundancy. Under 100 words but highly 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?

No output schema, but description fully explains return structure (summary block, advisories, links, alternative versions) and failure modes. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that scoped packages are accepted and version defaults to latest, enhancing understanding. Slight extra value justifies 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 it's a composite check for npm package evaluation, listing specific data sources (deps.dev, bundlephobia) and exact return fields. It distinguishes itself from sibling tools by its specific purpose.

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

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

Explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and provides exclusions ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly').

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

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

Annotations already indicate safe, idempotent, open-world behavior. Description adds valuable detail: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (truncation flagged).' Also mentions offsets for verification. 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?

Four sentences, front-loaded with core purpose. Each sentence adds distinct value: usage scenario, pairing, technical details. No redundancy or fluff.

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

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

No output schema, but description explains return: 'top-N passages with character offsets and similarity scores.' Covers chunking, metric, and input limits. Sufficient for a simple 3-parameter search tool.

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

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

Schema coverage is 100% with detailed descriptions. Description adds extra constraints: text max length (200K chars), limit range (1-20, default 5), and query examples. This provides more context than schema alone.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the resource (fetched text) and action (search with query). It differentiates from siblings by noting it's for records too large for the prompt and pairs with ask_pipeworx_grounded.

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

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

Explicit guidance: 'Use when the record is too big to cram into the prompt.' Describes the workflow with ask_pipeworx_grounded. Does not explicitly mention when not to use or list alternatives, but provides clear 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?

The description adds behavioral context: requires OAuth, phone verification for SMS, 10/day cap, webhook auto-disable. However, it implies a new subscription ID each call, which may contradict the idempotentHint=true annotation. No mention of idempotency or mutation semantics beyond what's implied.

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

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

The description is well-structured with clear sections for types and delivery. It is front-loaded with the purpose. While it is detailed, it remains focused and does not waste words. Could be slightly shorter but overall efficient.

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

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

Given the tool's complexity (3 params, nested objects, 5 enum values, delivery options), the description covers all necessary aspects: return value, prerequisites, limitations, and edge cases (auto-disable, phone cap). It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: provides examples and constraints for each type, details on delivery behaviors (email templated, SMS verified, webhook HMAC-signed with auto-disable). 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 the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and mentions the return value (new subscription id). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context: requires a Pipeworx OAuth account; explains supported types and delivery channels. 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about returning example questions and optional topic filtering, which is useful but not contradictory.

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?

Front-loaded with natural language queries, efficiently lists categories, and uses parentheses for examples. No redundant 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?

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, when to use, and parameter behavior. No gaps.

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

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

Schema coverage is 100% with description of topic parameter. Description adds context on how to use it (omit for full spread, pass topic to focus), exceeding schema alone.

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

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

The description states it's the onboarding entry point, returns category-bucketed example questions, and explicitly distinguishes from siblings by being the first tool to use when unsure.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and lists alternatives like ask_pipeworx, entity_profile, etc.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds beyond annotations: ownership enforcement, deactivation vs deletion, and preservation of historical data. Fully transparent.

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 concise sentences with no unnecessary words. Front-loaded with the action 'Cancel a subscription by id'.

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, behavior, ownership, side effects, and relation to other tools. Fully 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 single parameter 'id' described in schema. Description adds that the id is the subscription id returned by subscribe, linking to another tool – provides meaningful context beyond schema.

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

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

Description clearly states 'Cancel a subscription by id' – specific verb and resource. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explains ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated, not deleted, so historical events remain available via recent_alerts. Provides clear context on when to use and what happens, though does not explicitly 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, openWorldHint, idempotentHint), the description discloses crucial behavioral details: the two pipeline paths, exact percent-delta math for financials, and the semantic distinction between 'could_not_verify' (an error, not evidence) and 'unsupported' (no source found). This prevents misinterpretation of results and is essential context.

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

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

The description is long but every sentence earns its place, covering usage, pipelines, return values, and caller warnings. It is front-loaded with intuitive examples and includes a clearly marked 'IMPORTANT' warning section. The length is justified by the tool's complexity, though a slight trim could aid scanning.

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

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

Since there is no output schema, the description carries the burden of explaining return values. It lists all verdict types, mentions the value with citation and reasoning, and clarifies the meaning of error-related verdicts. It also covers the two execution paths and the consolidation of multiple calls, making it sufficiently complete for an agent.

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

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

The main description does not add parameter-level detail; both parameters are thoroughly described in the input schema (100% coverage). Since the description itself doesn't elaborate beyond the schema, it meets the baseline of 3 without adding extra semantics.

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

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

The description clearly identifies the tool as a natural-language claim verifier that returns a verdict, citing several example phrasings ('fact check', 'verify the claim that…'). It distinguishes itself from sibling tools by focusing on fact-checking with verdicts, making it stand out from generic question-answering or research 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?

It explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims (via SEC EDGAR fast path) and all other factual claims (grounded pipeline), giving concrete routing guidance. Mentioning that it replaces 4–6 sequential calls clarifies its efficiency advantage.

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