Ipma Pt

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it explains cost implications (default free, Anthropic requires BYO key), per-model return structure (score, confidence, signals, raw_response), and combined view. This goes well 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 3-4 sentences, front-loading the core purpose. Every sentence earns its place: clarity, return details, cost, use cases. No wasted words or redundancy.

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

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

Given 4 parameters (1 required) and no output schema, the description adequately explains return structure (per-model + combined) and key behaviors. It lacks explicit specification of the combined view shape, but overall is sufficiently complete for an LLM 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%, baseline 3. The description adds value by clarifying each parameter: entity examples ('Pipeworx', 'Acme Corp pricing'), models list of supported values, _apiKey purpose for Anthropic, and context disambiguation usage. This elevates understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the verb 'probe' and resource 'LLMs for entity knowledge', and distinguishes from sibling tools like entity_profile and deep_research by focusing on visibility scoring.

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

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

The description provides clear context for use: 'useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly exclude alternative tools or state when not to use. Without naming alternatives, it still gives strong situational guidance.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true; the description adds rich behavioral context: routing to sub-tools, filling arguments, returning structured answers with citations, working on every tier, and being a single fast call. 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 long but every sentence provides useful information: preference over web search, how routing works, trigger phrases, examples, and alternatives. It is front-loaded with its core purpose and organized clearly, making its length justified.

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

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

Without an output schema, the description compensates by describing the structured answer and citation URIs. It covers scope, usage triggers, examples, alternatives, and performance characteristics, offering a complete picture for a meta-tool of this complexity.

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

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

The schema already documents the 'question' parameter with aliases and 100% coverage. The description's examples are helpful but do not add new meaning about the parameter itself; the baseline of 3 is appropriate.

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

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

The description clearly states the tool's role: it routes questions to 5,443 tools across 1,415 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit guidance: prefer over web search for factual questions, provides trigger phrases ('what is', 'look up', 'get the latest'), concrete examples, and names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). It also positions itself as the default starting point.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful context about the experimental routing candidates being tested live, the current state (no active candidate), and that results are compared against the stable router. It also clarifies that this is a full working router, not a fallback, going beyond annotation coverage.

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 compact paragraph of about five sentences, each providing relevant information: beta status, identical nature, current candidate status, usage instruction, and experimental purpose. It is front-loaded with the core identity and avoids redundancy, though it could be slightly tighter.

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 router with no output schema, the description adequately covers what the tool is, how to use it, its experimental nature, and its relation to the stable version. It does not describe return values or error behavior, but the 'same response shape' reference partially covers that, and the high-quality annotations mitigate the gap.

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

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

The input schema covers all 6 parameters with a 100% coverage and clear alias descriptions. The description only mentions 'same arguments' without adding new meaning or usage details. This meets the baseline for high schema coverage but does not elevate above it.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, stating it is an identical universal router with the same 5,443 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx sibling and from other unrelated tools, making the purpose unambiguous.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives a clear use case. It implies the stable ask_pipeworx is the alternative for non-experimental use, but it doesn't explicitly state when not to use this beta version, so it falls slightly short of a 5.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses refusal reasons (not_in_source, no_tool_match, etc.), evidence quoting, and the extra LLM call cost. It explains the grounding behavior and refusal fallback, adding substantial behavioral context. No contradiction with annotations.

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

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

The description is dense but each sentence earns its place: purpose, mechanism, return format, refusal reasons, usage guidance, and tradeoff. It is longer than the ideal but not verbose, front-loading the key purpose first.

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 explicitly details the success and refusal return shapes, refusal reason enums, and the comparison with `ask_pipeworx`. It is complete for an agent to decide when to use this tool and what to expect.

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

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

Schema coverage is 100% and all parameters are aliases for `question` with descriptions. The tool description does not add parameter-level semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode' for high-stakes reads, with a specific grounding mechanism (extracts answer only from tool result). It distinguishes itself from sibling `ask_pipeworx` by noting the extra LLM call and refusal behavior, making it uniquely identifiable.

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 usage guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with the alternative: 'prefer ask_pipeworx for casual lookups.' Also mentions the cost tradeoff (one extra LLM call), giving clear when-to-use vs 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?

The description goes far beyond annotations: it details fan-out logic, response shapes, resolver contract, parent event extraction, news fallbacks, safety mechanisms for low-confidence matches and closed markets, illiquidity warnings, and cancellation rule parsing. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is long but front-loaded with purpose and usage. Section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) structure the information well. Every sentence adds value, though some lists (e.g., classifiers) could be summarized.

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

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

Despite no output schema, the description thoroughly explains response structure (result.market, result.analysis, result.evidence) and edge cases (low confidence, closed markets, wide spreads, cancellation rules). It covers all major behaviors needed for safe agent invocation.

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

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

All 3 parameters have schema descriptions, and the description adds substantial value: it explains the three input formats for 'market', the 'depth' enum options with defaults, and the 'include_raw' boolean with recommendations and size implications. This goes well beyond schema.

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

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

The first sentence clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies a specific verb (Research), resource (Polymarket bet), and distinguishes from siblings by focusing on single-bet research with data aggregation.

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

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

Explicit usage cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This tells the agent when to invoke. Missing explicit when-not-to-use alternatives, 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds significant context: for company type it pulls latest 10-K data with correct fiscal year handling, for drug type it pulls adverse-event counts and trial data, and it returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is moderately long but well-structured. It opens with trigger phrases, then defines the core purpose, followed by detailed behavior for each entity type, and closes with output format. Every sentence adds value, though some rephrasing could reduce verbosity without losing clarity.

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

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

Given the low parameter count (2), high schema coverage (100%), and no output schema, the description adequately covers the input requirements, expected output (paired data + citation URIs), and special behaviors (fiscal year handling, sorting by primary metric). It is complete for an agent to use this tool effectively.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds semantic value by explaining valid values (tickers/CIKs for company, drug names for drug), constraints (2–5 items, minItems/maxItems clarified), and how values map to entity types. While the schema already specifies enums for 'type', the description provides concrete usage examples and clarifies the difference between company and drug inputs.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs. It provides natural language triggers ('compare X and Y', 'which is bigger', etc.) and specifies the data pulled for each entity type (SEC EDGAR financials for companies, FAERS data for drugs). This differentiates it from siblings like entity_profile which likely handles single entities.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive for when to use this tool over alternatives. It also explains the behavior for each type and that results are sorted by primary metric, helping the agent understand when to invoke it.

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

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

Annotations already establish read-only, idempotent, open-world, and non-destructive traits. The description adds substantial beyond-annotation context: it is grounded (never invents answers, reports gaps[]), returns only resolvable citation URIs, uses parallel routing to many tools, semantic excerpting, contradiction scanning, and explicit latency ranges. 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 information-dense; every major clause contributes a distinct fact about scope, auth, alternatives, behavior, or output. It is front-loaded with the critical account requirement and the ask_pipeworx fallback, though the wall-of-text formatting could be more digestible with section breaks.

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

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

With no output schema, the description fully explains what the agent will receive: a findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers auth/premium constraints, latency, and topic caveats, making this complete for safe and correct invocation.

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

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

Schema coverage is 100% and the description enriches both parameters significantly. It explains the depth enum behavior (quick/standard/thorough, gap recovery, contradictions scan, paid tier, follow-up hops) and explicitly states that broad natural-language questions are acceptable because decomposition is the point, 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 identifies a specific action: grounded, multi-source research over Pipeworx's structured data sources in one call, with decomposition into facets. It distinguishes itself from siblings by explicitly naming ask_pipeworx for single lookups and open-web/current-news cases.

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

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

It gives explicit when-to-use guidance, stating this is best for broad/multi-part questions over structured data, and when not to use it: single lookups and breaking/current news should go to ask_pipeworx. It also covers account requirements, free vs. paid depth tiers, and expected latency, making the appropriate invocation context unambiguous.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N most relevant tools with names, descriptions, and full input schemas, and that results are 'ready to call directly, no second schema lookup needed.' No contradiction. Provides behavioral insights 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?

Single paragraph of three concise sentences. First sentence states core purpose and examples. Second sentence describes output and value. Third sentence provides usage guidance. No redundant information. 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?

Despite no output schema, description adequately covers what the tool returns: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly.' It also mentions limit parameter behavior. However, it could be more specific about the exact JSON structure of 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?

All 6 parameters have descriptions in the input schema (100% coverage). Description adds value by listing alias parameters (task, q, description, search) and explaining that the 'query' field accepts natural language with examples. This helps the agent understand how to use the parameters correctly.

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 uses specific verbs like 'find', 'browse', 'search', 'look up', and 'discover' to clearly state the tool's purpose. It lists a broad range of domains (SEC filings, financials, FDA drugs, etc.) and distinguishes itself from sibling domain-specific tools as a meta-tool for discovering which tool to use.

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: 'Call this FIRST when you have many tools available and want to see the option set'. Also provides context: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by examples. Implicitly advises against using for a single answer by saying 'not just one answer'.

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 and idempotentHint. The description adds behavioral context: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields (cik, filings, fundamentals, patents, news, LEI), and notes a soft-fail condition for patents. Does not contradict annotations.

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

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

The description is slightly long but front-loaded with examples and a clear purpose statement. Every sentence adds information (data sources, return fields, limitations). Could be more structured (e.g., bullet points) but remains efficient and readable.

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

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

Given only 2 required parameters and 100% schema coverage, the description provides comprehensive context: what data is fetched, how it is sourced (SEC, XBRL, etc.), what specific fields are returned, and known limitations (patent soft-fail). No output schema is needed; the description covers return value expectations sufficiently.

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 coverage is 100% with descriptions for both parameters. The description adds value by clarifying that 'type' only supports 'company' currently (with person/place coming soon) and that 'value' must be a ticker or zero-padded CIK, not a name. This context is not present in the schema alone.

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

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

The description starts with clear usage examples ('Tell me about X', 'research Acme') and explicitly states it provides a 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes from sibling tools like resolve_entity (for name resolution) and single-source lookups, making the purpose unambiguous.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes that names are not supported and advises using resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructive=true and idempotent=true. The description confirms deletion but adds little beyond the key detail already present in the schema. 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 concise sentences with front-loaded purpose. Every sentence adds value with zero waste.

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

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

Given the simple interface (one required param, no output schema), the description adequately covers purpose and usage. It also contextualizes with sibling 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% and the description merely repeats 'by key'. No additional constraints or format guidance are provided, meeting the baseline for high coverage.

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

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

The description clearly states 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' as the delete counterpart.

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

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

The description gives explicit usage scenarios ('when context is stale, task is done, or clear sensitive data') and advises pairing with siblings. While it doesn't explicitly state when not to use, the context is clear enough for an agent.

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

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

Describes the internal process: fetches page, extracts title/description/key links, emits standard format. Annotations (readOnlyHint, idempotentHint) are consistent and the description adds behavioral detail beyond them.

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

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

Two sentences: first states purpose and output, second lists use cases. No wasted words, front-loaded with core intent.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description fully covers what the agent needs: purpose, behavior, use cases, and output format.

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

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

Schema provides full description coverage (100%) for both parameters. Description adds minimal extra context (e.g., 'key links' hints at usage of max_links), but baseline is appropriate.

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

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

Description clearly states the verb ('Generate'), resource ('llms.txt file'), and purpose ('so AI crawlers can index the site cleanly'). It distinguishes from siblings like 'ai_visibility_check' by focusing on the specific output format.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing competitors. While no alternatives are named, the focused use cases provide sufficient guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to repeat safety. It adds behavioral details: returns multiple weather metrics, example usage, and that it is official IPMA data. 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 concise sentences plus an example. It front-loads the purpose and includes an example call, making it efficient and easy to parse.

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

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

With only one parameter and no output schema, the description comprehensively explains what is returned (temperature, precipitation, wind, etc.), making it complete for an agent to understand the tool's behavior.

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

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

The schema already covers the city parameter with examples and a tip to use ipma_locations. The description adds examples and notes accent-insensitivity, which provides extra context beyond the schema.

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

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

The description clearly states it returns the official IPMA 5-day forecast for a Portuguese city, listing specific cities and the data provided (min/max temp, precipitation, etc.). It distinguishes itself from sibling tools like ipma_sea_forecast and ipma_seismic by focusing on city weather.

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 city weather forecasts and provides an example call. It does not explicitly state when not to use it or mention alternatives, but the sibling tool names and context make the purpose clear.

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

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

Annotations already declare readOnly and idempotent; description adds what data is returned (globalIdLocal, coordinates) and scope (district capitals, islands). No contradiction.

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

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

Two tight sentences with example, no fluff.

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

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

No output schema, but description explains output components and data scope, fully adequate for a simple list tool.

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

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

Schema covers 100% of parameter; description adds 'accent-insensitive substring' and example, enhancing meaning beyond schema.

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

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

Clearly states it lists Portuguese cities and islands with codes and coordinates, using specific verb 'List'. Differentiates from sibling tools like ipma_forecast.

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 filtering example, implies use for obtaining location codes for other IPMA tools. No explicit when-not, but context sufficient.

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

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

Adds beyond annotations: specifies exact metrics returned (wave height, period, direction, SST) and geographic coverage (12 coastal zones, mainland, Madeira, Azores). Annotations already declare read-only, idempotent, non-destructive; description complements well.

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 plus an example, no wasted words. Front-loaded with key purpose, then details and example.

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?

Returns specific quantitative metrics (with units), covers all needed context for agent to select and invoke. No output schema needed as description explains return values adequately.

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

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

Schema covers both parameters with full description. Description adds contextual meaning: 'coastal zone filter' and example usage, plus info on omitting city for all zones. Baseline 3, description adds 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?

Clearly states it provides sea state forecast (significant wave height, wave period, wave direction, sea surface temperature) for Portuguese coast, covering specific zones. Distinguishes from sibling tools like ipma_forecast (weather) and ipma_uv_forecast.

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?

Mentions it's good for surf, sailing, and beach conditions, and gives an example call. Does not explicitly state when not to use or provide alternatives, but context from siblings implies differentiation.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds operational details: returned fields (time, magnitude, depth, epicenter region, coordinates, felt intensity), date coverage (last 30 days), and filtering behavior (excludes events without computed magnitude when min_magnitude set). This goes beyond annotations.

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

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

The description is a single substantial sentence with an example appended. It is concise and front-loaded with the core purpose. Could be structured as two sentences for improved readability, but no redundant text.

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

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

For a tool with no output schema, the description adequately covers return fields, time coverage, geographic scope, and filtering examples. It also explains behavior when min_magnitude is set. Given the parameter count and simplicity, it is complete.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds an example that demonstrates parameter combinations and default values (area defaults to 'mainland', days defaults to 7). This provides practical meaning beyond the schema alone.

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

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

The description clearly states 'Portugal earthquakes — recent seismic events recorded by IPMA for mainland Portugal + Madeira or for the Azores archipelago.' It specifies the resource (seismic events), verb (returns), geographic scope, and distinguishes itself from sibling tools like ipma_forecast and ipma_locations which cover different data types.

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

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

Provides context on usage with an example call and specifies time range ('roughly the last 30 days') and scope. While it doesn't explicitly state when not to use, the sibling tool set covers distinct domains (forecast, locations, sea, UV), so ambiguity is low. A more explicit alternative could improve it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds useful context: daily peak-hours, risk levels, city restrictions, and forecast duration. No contradiction. It 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?

Two sentences plus a code example. Extremely concise with no wasted words. Purpose is front-loaded and example clarifies usage.

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

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

No output schema exists, yet the description only briefly mentions 'risk level (Low to Extreme)' without detailing the return structure. For a simple tool, this may suffice, but more complete description of output format would be better.

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 one parameter (city). The description gives an example and lists city names, but does not add semantic detail beyond the schema. Baseline 3 applies.

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

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

The description clearly states the tool provides UV index forecasts from IPMA for Portugal, specifies time frame (~3 days), risk levels, and example cities. It distinguishes from siblings like ipma_forecast and ipma_sea_forecast by focusing on UV.

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 use when needing UV index for Portuguese cities, but does not explicitly state when not to use or suggest alternatives. The sibling context hints at other IPMA tools, but the description alone offers limited usage guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds context about returned fields and that it lists only active (unless include_inactive is true). No behavioral quirks mentioned, but sufficient given annotations.

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

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

Two sentences with no wasted words. Purpose is front-loaded, and usage is clearly stated in the second sentence.

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 one optional parameter and no output schema, the description covers purpose, return fields, and usage scenarios. Lacks mention of pagination or rate limits, but not critical for this simple 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?

Parameter schema coverage is 100% with a clear description. The description does not add further meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'list' and the resource 'caller's active subscriptions', and specifies returned fields. It distinguishes from siblings like subscribe/unsubscribe by providing usage context.

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

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

Explicitly states when to use (reviewing monitoring, finding id to cancel) but does not mention when not to use or alternative tools. Still provides 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 are all false (no hints), so the description carries full burden. It discloses rate limits (5 per identifier per day), that it does not count against quota, that the team reads digests daily, and that user prompts should not be pasted. This goes far beyond what annotations provide. 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 thorough but slightly verbose. It front-loads the main purpose and then covers usage, exclusions, and behavioral constraints. Each sentence adds value, though a few could be tightened. Overall, it is well-structured and organized for the complexity.

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

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

Given the tool's complexity (3 params, nested context, enum), the description is complete: it explains when to use it, what to include, what not to include, rate limits, quota impact, and follow-up effects (roadmap impact). No output schema is present, but the description sufficiently conveys what happens with the feedback.

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 does not meaningfully extend parameter meaning beyond the schema; it repeats enum definitions and message instructions already present in the schema. The additional 'don't paste the end-user's prompt' is a behavioral guideline, not a parameter semantics improvement.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This distinctly identifies the feedback purpose and differentiates it from sibling tools (none of which are feedback-related). The title and description align perfectly.

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 criteria: bug, feature/data_gap, and praise scenarios, each mapped to the correct type. It also states a clear exclusion: only for Pipeworx connection tools, not other MCP servers, and suggests filing feedback elsewhere. This directly addresses when not to use the tool and names the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). No contradictions with annotations.

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

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

Description is concise (3 sentences plus bulleted uses) and front-loaded with purpose. Every sentence earns its place. Could be slightly tighter, but no fluff.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is comprehensive: it explains what it returns, three use cases, data source, privacy, caching, and window semantics. No missing information.

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 with full enum. Description adds meaningful guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose the right window.

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 returns trending tools, packs, and call volume from Pipeworx agents. The verb 'returns' and resource 'trending' are specific, and the description distinguishes it from siblings like 'ask_pipeworx' or 'discover_tools' by focusing on real-time agent activity.

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

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

Lists three explicit use cases (hot data sources, canonical choice confirmation, alignment checking). While it doesn't state when not to use, the context is clear enough to avoid misuse among 30+ siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds substantial context: details on monotonicity checks, partition validation, semantic anchor (Jaccard threshold), partition filter (placeholder slugs), fill check with specific thresholds (realizable_edge_pp ≤ 0), and response structure. 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 long but well-organized: starts with core purpose, then parameter details, then behavior, then response structure. Every sentence adds value. Slight verbosity in middle sections but acceptable given 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 two parameters, no output schema, but the description fully explains the output (opportunities array, partition_check object, fill check results). It covers edge cases (low similarity, placeholder filtering, fill check warnings). For a complex arbitrage tool, this is complete.

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

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

Schema coverage is 100%, but the description dramatically expands meaning: explains the purpose of each parameter, expected formats (slugs, URLs), the behavior of each mode, and the interaction between parameters (e.g., event recommended for specific market). Goes well beyond the schema descriptions.

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

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

The description states a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between two modes (event and topic) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance: call with no args for trending scan, pass event for a specific market, or topic for cross-event scanning. It gives examples of slugs and warns when not to trade based on fill check results, and references 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 adds extensive behavioral context beyond annotations: caching behavior (1h KV cache keyed on knobs), segmentation into three model families with detailed methodology, edge calculation details (edge_pp_net after slippage, Kelly fractions), diagnostics to explain empty segments, and a caveat about Fed bets. All annotations (readOnly, openWorld, idempotent, non-destructive) are consistent and reinforced.

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

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

The description is dense but well-structured: purpose, model categories, response format, knobs, and diagnostics. While lengthy, every sentence carries important information. It could be slightly more concise by using bullet points or sections, but the front-loading of the core purpose and segmentation aids readability.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and the fields in each opportunity (edge_pp_net, kelly_fraction, etc.). Parameter descriptions are complete. The tool's complexity is fully addressed, leaving no critical gaps for an agent to understand its behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter semantics by explaining the rationale behind certain knobs (e.g., min_partition_leg_kelly as a per-leg filter for partition arbs) and how they interact (tradeable-edge filters). This adds value beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs and resources, and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection across multiple model families.

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

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

The description explicitly frames the use case as 'what should I bet on today' and explains how tradeable-edge filters (e.g., min_liquidity, max_spread_pp) help agents decide when to use it. It does not explicitly state when not to use it or compare to siblings, but provides sufficient context for appropriate invocation.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds rich behavioral detail: reads from daily snapshots, returns time-series with first_seen, trend, decay, expired opportunities, and limitations (60-day TTL, daily closes not intraday). 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 with front-loaded purpose, detailed response fields explained, and limitations at the end. Every sentence is informative and 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?

Despite no output schema, description comprehensively covers return structure (tracked[], expired[], snapshot_dates[]) with field explanations. For a 2-param tool, this is complete and leaves no ambiguity.

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. Description adds context: defaults (14 days, '1wk'), maximums (30 days), and explains the response structure, which supplements the schema.

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

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

Description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from siblings like polymarket_edges by focusing on time-series analysis rather than raw 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?

Description explains when to use (to assess edge age and decay) and provides context (fresh vs aged edge), but does not explicitly state when not to use or list alternatives. However, the context is clear enough for an agent.

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

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

The description discloses that it is a read-only simulation (consistent with annotations readOnlyHint=true) and details what it returns (top_of_book, vwap_fill_price, slippage_pp, etc.) and the verdict. It also warns about risks like thin_legs and forced_directional_risk, adding value 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 relatively long but efficiently structured with clear headings for single-market and basket modes, and uses caps for key phrases. It front-loads the main purpose and packs detailed information without redundancy. Slightly verbose but each sentence adds value.

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

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

Given the tool's complexity (two modes, many return fields) and lack of output schema, the description comprehensively explains return values and behavior for both modes. It covers edge cases like thin books and risk of partial fills, making it complete for agent decision-making.

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

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

Schema coverage is 100%, and the description adds significant context: for `side` it explains defaults and auto-behavior in basket mode; for `size_usd` it clarifies interpretation for buys vs sells and basket. This goes beyond the schema descriptions, ensuring agents understand parameter semantics fully.

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

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

The description clearly states it is a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific verbs like 'walks the ladder' and 'returns.' It clearly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by indicating it should be used before acting on those.

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.' It also explains consequences of not using it, such as partial basket fills converting arb into an unhedged directional position, providing clear context and alternatives.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral details: safety fields (compatibility_warning, temporal_alignment, skipped_cross counters) that explain potential mismatches and when spreads are meaningless. 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 fairly long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads purpose. While it could be slightly more concise, every sentence adds necessary 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?

No output schema, so the description must cover return values. It does so thoroughly: leg-by-leg prices, matched spreads, safety warnings, temporal alignment, and skipped counters. For a complex tool with two venues and multiple modes, this is complete.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining the two modes and how parameters interact (override logic). Baseline 3, but the extra context justifies a 4.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It describes two modes (topic shortcuts and explicit tickers) and what the tool outputs. It distinguishes from siblings like polymarket_arbitrage by focusing on cross-venue spread.

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

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

The description explains when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and warns that most pre-mapped topics return compatibility warnings, setting realistic expectations. It does not explicitly contrast with sibling tools, 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 provide readOnlyHint and idempotentHint; description adds scoping to identifier, behavior when key is omitted, and pairing info. No contradiction.

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

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

Three sentences, each adds value. Front-loaded with action. No wasted words.

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

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

With one optional parameter and no output schema, description fully explains what the tool does, when to use it, and how it pairs with siblings. 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%, so description adds limited extra meaning beyond the parameter description. The 'omit to list all keys' is already in 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 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb and resource. Distinguishes from sibling tools like remember and forget.

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

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

Explicitly says 'Use to look up context the agent stored earlier' and mentions pairing with remember and forget. 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?

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds value by explaining the mark_read side effect (marking events as read) and stating that polling works fine, confirming safe repeated use. 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 concise—three sentences total—with the most critical information (purpose and return data) in the first sentence. Every sentence adds value, no redundancy.

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

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

The description covers the key aspects: what is returned, filtering options, mark_read behavior, and availability via HTTP. Although it doesn't detail pagination or limit limits, those are in the schema. With no output schema, the return fields are adequately stated.

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 descriptions cover all parameters (100% coverage), but the description enriches understanding by providing examples ('sec_8k' for type) and clarifying the effect of 'mark_read' for future calls. This goes beyond the schema's basic property descriptions.

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

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

The description clearly states the action ('Pull fired events') and the resource ('from your subscription feed'), specifying exactly what is returned (source, citation_uri, raw payload). This distinguishes it from sibling tools like 'list_subscriptions' which manage subscriptions rather than retrieve events.

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

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

The description explains when to use the tool (to fetch recent alerts) and provides usage context like filtering options and the mark_read flag. It also mentions an alternative access method (HTTP GET endpoint) but does not explicitly exclude usage scenarios or compare to siblings.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), description discloses fan-out to multiple sources, real-time fallback behavior, and return structure (grouped changes, total count, citation URIs). No contradiction with annotations.

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

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

Single dense paragraph, front-loaded with query patterns. All information is relevant and none redundant. Slightly unstructured but 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 moderate tool complexity (multiple sources, fallback, soft-fail), description covers all essential aspects: sources, fallback, return format, parameter usage, and sibling distinction. No output schema, but return structure is described adequately.

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

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

Schema covers all parameters with descriptions. Description adds practical context: `type` is only 'company', `value` accepts ticker or CIK, `since` example suggests typical monitoring period. Adds value 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 it provides a change feed for a company in a given window, combining multiple sources. It uses typical query examples and explicitly distinguishes from sibling tool entity_profile.

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

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

Provides explicit examples and when to use entity_profile instead. Details fallback logic between GDELT and GNews, and the soft-fail for USPTO. Parameter `since` is explained with both ISO and relative formats, including a recommended '30d' or '1m'.

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

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

Annotations already provide idempotentHint and destructiveHint; description adds valuable context about scoping by identifier, persistent vs. anonymous memory, and duration. No contradictions.

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

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

Four sentences, each earning its place: purpose, when to use, storage details, pairing with siblings. Front-loaded with key action.

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

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

For a simple key-value store tool with 2 parameters and no output schema, the description adequately covers persistence, scoping, and usage. 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 descriptions fully cover both parameters with examples; description reinforces purpose but adds minimal new information 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?

Description uses a specific verb ('Save') and resource ('data'), and includes examples that clearly differentiate from sibling tools like 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 you discover something worth carrying forward') and lists example scenarios. Could be improved by mentioning when not to use (e.g., large data) but overall clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds meaningful context beyond that: each call cascades through multiple endpoints internally, replaces 2-3 manual lookups, and returns specific citation URIs. This gives insight into the tool's internal behavior and output characteristics.

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

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

The description is front-loaded with the core purpose and example queries, then organized by supported types. Every sentence provides value: examples, return details, and efficiency claims. Despite being longer than minimal, it is well-structured and free of filler.

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

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

Given there is no output schema, the description adequately explains return values (ticker, CIK, company_name, RxCUI, ingredient, brand, citation URIs). Along with annotations covering safety and schema covering parameters, the description completes the picture for a lookup tool.

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

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

Schema coverage is 100%, so baseline is 3. The description augments the schema with concrete examples (e.g., ticker 'AAPL', CIK '0000320193', drug 'ozempic') and clarifies behaviors like auto-disambiguation for company inputs, which goes beyond the raw schema definition.

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: resolve a user-spoken name to the canonical/official identifier other tools require. It uses specific verbs ('resolve', 'look up', 'find') and distinguishes from siblings by noting it provides IDs needed as input by other tools, making it a foundational lookup step.

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.' This directly tells when to use the tool. It does not explicitly name alternative tools or provide when-not-to-use scenarios, but the 'Use FIRST' instruction implies that if you already have an ID, this tool is unnecessary.

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 behavioral context: it explains that the tool 'probes each entity... with ai_visibility_check, ranks by score, surfaces which is most/least recognized,' and describes the output format. 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?

Three sentences, each earning its place. The core purpose is front-loaded, followed by how it works and a practical example. No unnecessary words 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?

Given the tool's complexity (multi-entity comparison, use of sub-tool), the description is quite complete: it explains the mechanism (probes with `ai_visibility_check`), output format (ranked list with score, confidence, signal density), and use case. Minor gaps: no mention of error handling or rate limits, but overall sufficient for agent understanding.

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

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

Schema description coverage is 100% for all 4 parameters. The description adds significant meaning for the `entities` parameter by stating that the first entry is treated as the 'subject' for narrative and the rest as competitors. It also contextualizes probing with `ai_visibility_check` and mentions model options briefly. Provides value beyond schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), resource (AI visibility), and distinguishes from the sibling `ai_visibility_check` by indicating it is a comparative version for multiple entities. Concrete example usage is provided.

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: 'Useful for competitive AI-marketing audits.' It implies the context but does not explicitly mention when not to use or provide alternative tools like `ai_visibility_check` for single entities. Clear context but no 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 description adds behavior beyond annotations: mentions partial failures, potential 5-30s delay for first bundlephobia measurement, and that sources_failed lists timeouts. Annotations already indicate readOnly and idempotent but description adds operational nuances.

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

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

Single paragraph efficiently packs all key info: purpose, sources, usage, constraints, return structure, and edge cases. No wasted words, 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 tool with 2 params and no output schema, the description fully explains return content (summary block, advisories, links, alternatives) and error behavior. It's self-contained enough for an agent to invoke correctly.

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

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

Schema already describes both parameters well (100% coverage). Description adds value by noting scoped package support and version defaulting to latest, which are not in schema descriptions.

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

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

The description clearly states it's a composite npm package evaluation tool, specifying it checks license, advisories, version history, bundle size, and ESM/tree-shake support. This differentiates it from sibling tools like scan_competitor_ai_presence and other unrelated tools.

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

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

Explicitly advises use when an agent asks about package safety, popularity, or size impact. Also clarifies scope: NPM only in v1, with alternatives for other ecosystems. This helps the agent choose correctly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral details beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character cap (200K with truncation flag), and return structure (passages with offsets and similarity scores).

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 plus a technical note, no wasted words. Critical information is front-loaded: purpose, usage context, and key differentiators.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores), covers technical details, and addresses edge cases (truncation). Given the tool's complexity, this is thorough and complete.

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

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

Schema coverage is 100%, but the description adds meaning by clarifying the text parameter as a previously fetched document and providing concrete query examples. It also reinforces the 200K char limit. While helpful, it could elaborate on the limit parameter format or default behavior.

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

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

The description clearly states it performs semantic search inside a fetched record, using the verb 'search' and specifying the resource context. It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded and its unique capability to return passages with character offsets.

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

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

Explicitly advises use when the record is too large for the prompt, explains it saves context, and references an alternative (ask_pipeworx_grounded). However, it does not explicitly state when not to use or list all alternatives, leaving some room for improvement.

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

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

The description discloses behavioral traits such as the need for an OAuth account, SMS rate limits (10/day), the one-time return of webhook secrets, and auto-disable after 10 consecutive webhook failures. These details go beyond the annotations, which mark the tool as mutable and non-destructive but do not mention these specifics.

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

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

The description is dense but well-structured, front-loading the main purpose. While every sentence adds value, it could be slightly more concise by using bullet points or shorter sentences without losing clarity.

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

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

Given the 3 parameters and lack of an output schema, the description covers all necessary aspects: supported types, required params, delivery options, prerequisites (OAuth), limitations (SMS cap), and edge cases (webhook secret, auto-disable). It is fully sufficient for an AI agent to use the tool correctly.

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

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

With 100% schema description coverage, the description adds significant meaning beyond the schema by providing concrete examples for each type's params (e.g., sec_8k items, polymarket_edge topics) and detailed delivery channel formats (E.164 phone, email validation, webhook signing).

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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It lists supported event types and delivery channels, distinguishing it from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description specifies that a Pipeworx OAuth account is required and that anonymous/BYO users cannot persist subscriptions. It provides examples of each subscription type and delivery options, but does not explicitly state when to use this tool over alternatives like recent_alerts.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context about the return format (category-bucketed example questions with exact tool+argument shapes) and the optional topic filtering, which goes 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 well-structured with a list of example prompts followed by a clear explanation of what the tool returns and how to use it. While it is somewhat lengthy, every sentence provides useful information with no redundancy.

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

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

Given the single optional parameter and no output schema, the description provides complete context: purpose, when to use, output format, and parameter semantics. No gaps are apparent.

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% as the only parameter 'topic' is described. The description adds meaningful context by listing valid topic values (finance, pharma, etc.) and explaining that omitting it gives a full spread while specifying it focuses the results, which goes beyond 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 explicitly states the tool's purpose as an onboarding entry point for users new to Pipeworx, returning category-bucketed example questions with tool details. It distinguishes itself from siblings by being the first tool to use when you don't know what Pipeworx can do.

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

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

The description clearly states when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains how to focus with the optional topic parameter, but does not explicitly mention when not to use it or provide direct 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?

The description reveals that cancellation deactivates rather than deletes the subscription, preserving historical events—context that the annotations (idempotentHint, destructiveHint) only hint at. This adds value beyond annotations and is consistent with them.

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

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

The description is two sentences long, front-loads the primary action ('Cancel a subscription by id'), and provides necessary additional context without any wasted words.

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

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

For a simple one-parameter tool, the description covers purpose, behavioral implications (ownership, deactivation), side effects (historical events preserved), and links to a related tool (recent_alerts). No output schema is needed, and the description is 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 input schema covers the single parameter 'id' at 100% with a basic description. The tool description adds value by noting the id is 'returned by subscribe', linking to the subscription creation tool—a useful cross-reference not present in the schema alone.

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

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

The description clearly states the verb 'Cancel' and resource 'subscription by id'. It distinguishes itself from sibling tools like 'subscribe' (creating) and 'list_subscriptions' (viewing) by focusing on cancellation. The mention of 'recent_alerts' for historical events further clarifies its role.

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 ownership enforcement ('you can only cancel your own subscriptions'), which is a key usage constraint. It also describes the deactivation behavior and links to 'recent_alerts' for history, but lacks explicit when-not-to-use guidance or comparisons to alternative tools like 'subscribe' or 'list_subscriptions'.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: it returns a verdict (with five possible values), the actual value with pipeworx:// citation, and reasoning. It details the exact percent-delta math for financial claims and verbatim evidence for others. No contradiction with annotations.

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

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

The description is relatively long but every sentence provides value: purpose, examples, routing logic, output specification, efficiency claim. The front-loaded examples quickly orient the agent. Minor redundancy ('natural-language claim verification' appears early and later), but overall well-structured for 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?

Given no output schema, the description fully explains the output: verdict types, actual value with citation, reasoning. It covers all necessary aspects: when to use, how it works, parameter details, routing logic. For a tool with moderate complexity (two parameters, two routing paths), the description is complete.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema: it explains how tolerance_pct overrides the implied tolerance from the claim wording, sets a default cap of 5%, and provides example use cases (e.g., 1-2% for hallucination detection). This helps the agent decide appropriate parameter values.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources. It provides specific examples of usage ('Is it true that...', 'fact check', etc.) and distinguishes two routing paths: SEC EDGAR for financial claims and a grounded pipeline for others. This differentiates it from sibling tools like 'deep_research' or '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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains the two distinct processing paths for financial vs. other claims and claims it replaces multiple sequential calls. However, it does not explicitly mention scenarios where this tool should NOT be used, though the purpose is clear enough.

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