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 already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context beyond that: it autonomously routes to the correct tool and fills arguments, spans 5,710 tools / 1,494 sources, and discloses the output contract (structured answer with stable pipeworx:// citation URIs). It doesn't cover failure modes (no match, ambiguous question), but that gap is minor given the 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 strongly front-loaded ('PREFER OVER WEB SEARCH') and information-dense, which suits a broad router tool. However, it is verbose and redundant: 'even if web search could also answer it' appears twice, and the trigger-phrase list ('what is', 'look up'...) overlaps with the later 'what is the capital of France' example. Most sentences earn their place, but the repetition and near-duplicate example sections cost it a higher score.

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

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

For a high-complexity router with a single required parameter and no output schema, the description is thorough: it covers return format (structured answer with stable citation URIs), routing/argument-filling behavior, domain coverage, trigger conditions, and named exclusions to deep_research and search_within. The remaining gaps — behavior on ambiguous or no-match questions, latency or cost characteristics — are secondary and unlikely to prevent an agent from invoking it correctly.

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

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

Schema description coverage is 100%: every one of the six parameters is documented, including the primary 'question' parameter and its five aliases (q, text, input, query, prompt), so the schema carries the full burden. The description contributes example questions that illustrate well-formed queries, but it adds no parameter-level semantics beyond what the schema already states. The 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 states a specific verb+resource behavior: it routes a natural-language question to the right tool among 5,710 tools across 1,494 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It distinguishes itself from web search (explicitly preferred over it), deep_research (in-depth questions), and search_within (systems/text/6M context), so an agent can tell it apart from siblings without opening schemas.

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

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

The description provides explicit when-to-use guidance: trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), a concrete domain list (SEC filings, FDA, FRED/BLS, USPTO, weather, clinical trials, etc.), and an explicit 'PREFER OVER WEB SEARCH' directive. It also names when-not-to-use alternatives: 'For more in-depth questions use deep research' and 'For systems, text search, and the 6M token context window, use search_within.' This is exactly the explicit when/when-not/alternatives structure the rubric rewards.

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

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

The annotations already carry the safety profile (read-only, idempotent, non-destructive), so the bar for added value is moderate and this description clears it. It discloses the crucial dynamic trait that annotations cannot: candidate routing improvements are enabled live whenever one is under test, and none is active now (retired 2026-07-26), so behavior currently matches ask_pipeworx exactly. The 'falls back to nothing — this IS a full working router' clarification prevents a plausible misconception about beta status.

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

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

Five sentences and roughly 95 words, with identity front-loaded before current state and usage guidance. Every sentence earns its place: the 5,710-tool scope, parity with ask_pipeworx, the live candidate behavior, and the full-router clarification are all load-bearing. It is a single dense paragraph rather than structured bullets, but nothing is wasted.

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

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

With no output schema, the description compensates by stating the response shape is identical to ask_pipeworx. It covers identity, current state, usage condition, and experimental comparison purpose — enough for an agent to invoke it safely and correctly. The main dependency is that 'same arguments' and 'same response shape' assume knowledge of ask_pipeworx, which the sibling list makes readily resolvable.

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

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

Schema coverage is 100%, so the schema already documents all 6 parameters — question with a full natural-language description plus five aliases each labeled 'Alias for question.' The description adds only the cross-tool statement that arguments are identical to ask_pipeworx, which lets an agent reuse knowledge from the sibling tool. That is a modest increment beyond the schema, matching the baseline of 3.

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

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

States a specific identity and function: the beta variant of ask_pipeworx, an identical universal router over 5,710 tools with the same arguments and response shape. It immediately differentiates itself from the stable sibling tool while naming what it actually does (routing natural-language questions). Concrete scope and a clear verb+resource make the purpose unmistakable.

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

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

Explicitly tells the agent when to choose it: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the evaluation role against the stable router. It names the key alternative (ask_pipeworx) and the selection condition. It stops short of full when-not guidance — no exclusions versus ask_pipeworx_grounded or other siblings — which keeps it a 4 rather than 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 the annotations (read-only, idempotent, open-world), the description discloses that the tool extracts answers using only tool-result content, provides a detailed success return contract, and lists every refusal reason. It also notes the extra LLM call cost, which is operationally significant. No contradiction with annotations.

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

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

The description is front-loaded with the key purpose and differentiator. It packs return shapes, refusal semantics, use cases, and a cost tradeoff into dense but purposeful prose; every sentence contributes to correct invocation and expectation-setting.

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

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

This is a complex tool with no output schema, yet the description fully covers success and failure outputs, the sourcing behavior, and when to prefer the cheaper sibling. Combined with the complete input schema, an agent has everything needed to invoke it correctly and interpret its responses.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including aliases for the question parameter. The description adds context about how the question routes across many tools, but it does not add parameter-level meaning beyond the schema, so 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 states a specific, differentiated purpose: a hallucination-resistant grounded answer mode for high-stakes reads. It explicitly contrasts itself with ask_pipeworx by naming the same routing but a stricter extraction behavior, so an agent can tell them apart without opening the schema.

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: whenever an answer will be quoted, cited, or acted on, and for high-stakes domains such as financial verdicts, legal claims, and medical lookups. It also states when not to use it — casual lookups — and directs the agent to ask_pipeworx instead.

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 mark the tool read-only, idempotent, and non-destructive; the description adds substantial behavioral context: account/tier requirements, parallel decomposition, findings packet fields, gaps[], contradictions[], semantic excerpting, citation URI resolvability, and expected latency. This makes output behavior and constraints fully predictable.

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 most decision-critical constraints (account, tier, alternative) are front-loaded, followed by mechanics and output packet details. It is long, but nearly every sentence carries operational value; some depth details repeat the schema, which prevents a 5.

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

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

For a complex two-parameter tool with no output schema, it covers auth, tier, exclusions, source scope, decomposition, output structure, gap/contradiction behavior, citation fetchability, excerpting, and latency. An agent has everything needed to select and invoke it correctly and anticipate results.

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

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

Input schema coverage is 100%, so the schema already explains 'question' and 'depth', including the paid thorough tier and contradiction scans. The description reinforces depth behavior and gives question examples, but adds little semantically beyond what the schema already provides.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1494 structured data sources in one call, explicitly distinguishing from open-web search. It also names the sibling ask_pipeworx for different use cases, so an agent can differentiate the tool without opening schemas.

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

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

It explicitly says when to use deep_research — broad/multi-part questions over structured data — and when not to: not signed in or single lookup, use ask_pipeworx instead. The paid-tier constraint for 'thorough' plus fallback instructions leave no inference needed.

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?

With annotations only indicating non-read-only, non-destructive, non-idempotent, the description carries the burden and delivers richly: explains the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limits ('Rate-limited to 5 per identifier per day'), and operational context ('The team reads digests daily and signal directly affects roadmap'). It also notes 'Free; doesn't count against your tool-call quota,' which is beyond annotation scope. 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 longer than a typical tool description, but every sentence conveys a distinct, necessary fact (purpose, use cases, exclusions, claim-token mechanics, rate limit, quota, roadmap). It is well-structured and front-loaded with the primary purpose. A 5 would require even tighter wording; this is appropriately sized for the informational density required.

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

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

Given the tool's complexity (4 params, nested object, optional claim_token flow, no output schema), the description covers all essential aspects: what it does, when/not to use it, how the claim_token callback works, what type of messages to write, and operational constraints (rate limit, free quota, roadmap impact). It fully compensates for the lack of an output schema by describing what a filing returns ('a claim_token' and later 'status').

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra value beyond the schema by clarifying the real-world usage of parameters: e.g., claim_token's round-trip flow and that message should be 'in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This enriches the schema's already-good definitions, justifying a 4.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' and enumerates the types (bug, feature, data_gap, praise). This clearly distinguishes the tool from every sibling (research, forecasts, recall, etc.), which all serve different purposes.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead,' and instructs not to paste the end-user's prompt. This is exemplary 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, 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 already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: compatibility codes, skipped comparison counters, low-confidence pairs, temporal alignment fields, and the rule that legs with unknown metric_type or match_subtype are never paired. This is exactly the kind of operational behavior an agent needs to interpret results safely. There is no contradiction with the annotations.

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

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

The description is long, but the tool is genuinely complex and has no output schema, so the length is largely justified. It is well-structured: purpose first, then modes, response shape, safety fields, compatibility codes, and a closing caveat. A few details could be tighter, but the organization makes the density acceptable.

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

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

Given the lack of an output schema, the description is remarkably complete: it specifies the response shape (leg-by-leg prices, top_spreads_pp, skipped_unclassified, low_confidence_pairs, temporal_alignment, skipped counters), the safety fields, the compatibility code semantics, and the two invocation modes. An agent has enough information to call the tool correctly and interpret the results, including the non-obvious caveat that compatibility fields can be non-empty even when matched_pairs is positive.

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

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

The input schema already covers 100% of parameters, so the baseline is 3, but the description adds meaningful semantics by explaining that topic is a pre-mapped macro shortcut that auto-fetches the matching event on each venue, while the explicit parameters enable custom pairings and override the topic-mapped side. This goes beyond the schema by clarifying the interaction between the two modes, even though it does not specify behavior when no parameters are provided.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, naming both resources and the relationship between them. It differentiates itself from sibling tools by explicitly defining the two-venue comparison and the two modes of operation. This is far more specific than a vague 'compute spread' or a tautological restatement of the tool name.

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

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

The description provides strong usage context by explaining both the topic shortcut mode and the explicit ticker/slug mode, and it warns that most pre-mapped topics currently return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly name alternatives among the sibling tools, so it stops short of a full when-to-use-vs-others statement, but the intra-tool mode guidance 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 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 cover read-only, open-world, idempotent, and non-destructive hints. The description adds substantial behavioral content: cascading through multiple internal endpoints, graceful degradation when external sources fail, explicit `unresolved` output for unresolvable identifiers, and detailed source-labelling behavior (SEC EDGAR, GLEIF, OpenFIGI). This far exceeds what annotations alone provide.

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

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

The description is long but densely informative, front-loaded with query examples and a clear directive. Every major behavior is justified, and the complexity of the tool justifies the length. However, some clauses are wordy (e.g., 'cross-source identity spine') and could be tightened without losing content.

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 is present, but the description explains what is returned for each type: company returns CIK, ticker, company_name, LEI with ownership, FIGI, and an `unresolved` list; drug returns RxCUI, ingredient, brand, and citation. It also covers source availability and degradation. It stops short of detailing the response JSON structure, which would be helpful but is not essential for agent usage.

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

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

Schema description coverage is 100% for both parameters, so baseline is 3. The description enriches the `value` parameter by explaining that ISINs resolve to the legal entity via GLEIF's ISIN-to-LEI mapping, covering non-US issuers, and provides additional examples for both `type` values. This adds meaning beyond the schema's generic descriptions.

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

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

The description explicitly states the tool's function: resolving a user-spoken name to canonical/official identifiers, with concrete example queries like 'What's the ticker for...' and 'find the CIK for...'. It distinguishes itself from sibling tools by noting these identifiers are what other tools require as input, positioning resolve_entity as the front-end resolution 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?

The description gives an explicit directive: 'Use FIRST whenever you have a name but need an ID.' This is a clear when-to-use, but it does not name specific alternative tools for when an ID already exists, nor does it provide when-not-to-use scenarios beyond implication.

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 declare read-only, open-world, idempotent safety, and the description adds substantial behavioral nuance beyond that: the distinction between 'could_not_verify' (pipeline failure, not evidence) and 'unsupported' (no source exists), the routing logic, and the requirement not to present could_not_verify as evidence. This is exactly the kind of context an agent needs to interpret results correctly.

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 carries information: query examples, routing rules, verdict values, failure semantics, and call-efficiency benefit. It is front-loaded with natural-language triggers. Slightly verbose but structured clearly and without redundancy.

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

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

With no output schema, the description carries full responsibility for explaining return values. It enumerates all possible verdicts, mentions 'grounded or structured actual value with pipeworx:// citation,' and details the error semantics of could_not_verify vs unsupported. For a tool with two routing paths and nuanced outcomes, this is exceptionally complete.

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

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

Schema description coverage is 100% and both parameters (claim, tolerance_pct) are already well documented with examples and constraints. The description's example claims reinforce the schema but do not add new parameter-level semantics, so the baseline of 3 applies.

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

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

The description opens with specific query patterns and immediately states 'natural-language claim verification against authoritative sources,' giving a clear verb (verify), resource (claims), and scope (against authoritative sources). It also distinguishes itself from siblings by noting it 'Replaces 4–6 sequential calls,' making its unique position explicit.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and outlines two routing paths (SEC EDGAR for financial claims, grounded pipeline for others). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it stops short of full exclusion guidance.

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