Twilio

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

Annotations already indicate safety (readOnlyHint, idempotentHint, etc.). The description adds valuable behavioral context: default free model, BYO key for Anthropic with cost implications, and return structure (per-model fields + combined view). 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 two sentences: first sentence captures the main function and default, second sentence adds key details and use cases. No unnecessary words or repetition; front-loaded with the most essential information.

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

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

Despite lacking an output schema, the description outlines the return fields (score, confidence, signals, raw_response per model plus combined view). It covers parameter behavior, cost implications, and use cases. However, it doesn't define 'signals' or 'raw_response' detail, leaving some minor 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% (all 4 parameters have descriptions). The tool description adds meaning beyond the schema by explaining the default model, the free vs. paid distinction, and the purpose of the 'context' parameter for disambiguation.

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

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

Description clearly states the tool probes LLMs for knowledge about a specified entity and returns a visibility score (0-100). It specifies the default model and optional Anthropic integration, distinguishing it from sibling tools like 'scan_competitor_ai_presence' which may have a different focus.

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 lists specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use this tool or compare it with alternatives. The context is clear but lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value by explaining that it routes to one of 5,635 tools across 1,477 sources, fills arguments, and returns structured answers with stable citation URIs — behavioral details not present in annotations. It also notes the call is fast and works on every tier. Missing rate-limits or failure modes, but for a read-only router this is sufficient.

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 effectively front-loaded: the purpose and default usage appear in the first sentence, followed by concrete examples and alternatives. Every sentence earns its place, but the length could be trimmed without losing critical info, so it is not 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 general-purpose entry point with no output schema, the description fully equips an agent: it covers scope, examples, alternatives, expected output (structured answer with citation URIs), and performance characteristics. Nothing an agent needs to decide when to call it is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds no additional semantic meaning beyond the schema, except clarifying that 'question' accepts aliases (q, prompt, text, input, query), which is also mirrored in the schema. Thus, the description does not meaningfully enhance parameter understanding; the schema already carries the weight.

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 'PREFER OVER WEB SEARCH' and immediately states the tool's core function: answering questions about current or historical data across a wide range of domains. It names the resource (Pipeworx) and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart without inspecting their 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?

Provides explicit guidance on when to use this tool (for factual questions, 'what is', 'look up', etc.), and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad multi-part questions). It even gives concrete examples and states it is the default entry point, making the usage context unambiguous.

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

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds valuable context beyond annotations: it discloses the experimental nature, that behavior may differ when a candidate is active, that currently no candidate is active making it identical to stable, and that it falls back to nothing (it's a full router). This transparency about potential behavioral variation is useful for an agent.

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 concise and well-structured. It front-loads the purpose (beta router), then clarifies the current state and usage guidance. Every sentence adds context: the beta nature, the no-candidate status, the comparison purpose, and the full functionality. It could be tightened slightly, but it's not bloated and flows logically.

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

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

For a simple single-parameter router with safety annotations and no output schema, the description is quite complete. It explains the beta status, current behavior (identical to stable), usage, and that it is a full working router. It references the response shape being the same as ask_pipeworx, which is acceptable given the sibling context. Nothing critical is missing for an agent to decide whether and how to use it.

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

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

Schema description coverage is 100% with question and its aliases fully described in the schema. The description only says 'same arguments' without adding any new meaning about how to structure the question or what makes a good query. With full schema coverage, baseline is 3, and the description provides no extra semantic value beyond confirming the parameter set is identical to ask_pipeworx.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,635 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements, and explicitly notes it is a full working router. This is a specific verb+resource definition that differentiates from siblings.

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

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

It gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' This implies a condition for use (wanting newest routing) and by extension not using it when you want stable routing, though it doesn't explicitly state an exclusion. It also explains that results are compared against the stable router, providing clear context for when this tool is appropriate.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses the tool's refusal behavior, the extra LLM call cost, the return structure (with evidence and confidence), and the refusal reasons. It also clarifies that it only uses tool result content, preventing agent invention. This substantially 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 dense but every sentence earns its place: it defines the mode, how it works, the return/refusal contract, the use cases, and the cost trade-off. Information is front-loaded with the core purpose first, followed by usage guidance. No fluff 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?

For a tool with no output schema, the description fully explains the return format and refusal reasons. It covers the key differences from the sibling, the exact scenarios to use it, and the cost implication. Given the tool's complexity (multiple aliases, refusal logic), nothing essential is missing for an agent to call it correctly and interpret results.

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

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

Schema description coverage is 100% — all six parameters (including aliases) are documented in the schema. The description does not add parameter-specific semantics beyond confirming the question is natural language. With full schema coverage, the baseline of 3 is appropriate; the description adds no extra value for parameters.

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: a hallucination-resistant answer mode that extracts answers only from tool results, with explicit refusal handling. It distinguishes itself from the sibling ask_pipeworx by naming the shared routing and the key differentiator (evidence extraction and refusal behavior). This is a specific verb+resource+scope statement.

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

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

The description explicitly states when to use it ('high-stakes reads', 'whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups') and why (extra LLM call cost). It names the alternative tool and gives a concrete selection criterion, leaving no ambiguity.

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, destructiveHint. Description adds extensive behavioral details: resolver contract, parent event extractor, news fallback handling, safety short-circuits, wide spread handling, and resolution-rule risk. 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 very detailed and front-loaded with purpose. However, it is quite long and could be trimmed without losing essential information. Every sentence adds value, but conciseness is compromised.

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

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

Given the tool's complexity (multiple fan-out categories, various response shapes, safety considerations), the description is highly complete. Covers input variations, output structure, edge cases like closed markets, and caveats like low-confidence matches.

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

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

Schema coverage is 100%, baseline 3. Description adds context: depth enum explained with quick/thorough behavior, market parameter clarifies accepted formats, include_raw describes size implications and use cases. 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?

The description clearly states the tool researches Polymarket bets using Pipeworx data, with specific verb ('Research') and resource ('Polymarket bet'). It distinguishes from siblings by focusing on bet research and mentions inputs like slug, URL, or question text.

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

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

Explicitly states when to use: 'for should I bet on X, what does the data say about Y, or is there edge in Z'. Does not directly compare to siblings, but 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 mark the tool as read-only, open-world, idempotent, non-destructive. The description adds significant behavioral details: for company type it pulls latest 10-K data from SEC EDGAR/XBRL with correct fiscal year handling, for drug type it pulls FAERS counts, and it returns sorted results with citation URIs. No contradiction.

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

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

The description is a single well-structured paragraph. It front-loads trigger phrases, then concisely explains behavior for each type, and finally notes return format. No unnecessary words.

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

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

Given no output schema, the description appropriately hints at return format (paired data + citation URIs) and sorting. For a tool of this complexity, it covers essential aspects. Could mention the returned fields more explicitly, but overall adequate.

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

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

Schema coverage is 100% for both parameters. The description adds meaning by explaining the interpretation of values arrays (tickers vs drug names) and the behavior per type, plus sorting by primary metric. This adds value beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, given specific trigger phrases. It distinguishes from sequential lookups by explicitly recommending this tool over them.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example queries. While no explicit when-not scenarios are given, the guidance is clear and strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond these: the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] array for unanswered facets (never invented), contradictions[] for disagreements, the hop field and citation_uri, semantic excerpting instead of head-truncation, and expected latency (15-60s, up to ~90s for thorough). It also discloses the account and paid-tier dependency. This exceeds the annotation baseline richly.

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

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

The description is long but every sentence earns its place. It is front-loaded with the most critical constraints (account requirement and alternative) before the core functionality. It uses compact punctuation (semicolons, em dashes) to pack information without fluff. Each clause adds distinct information: sources, parallelism, return fields, use-case guidance, depth behavior, timing, and technical caveats. There is no redundancy or filler.

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

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

Given the complexity of this tool (parallel routing, 5635 tools, multi-hop depth) and the absence of an output schema, the description is exceptionally complete. It specifies the return packet fields, the gaps[] semantics, contradictions[], hop and citation_uri, excerpting behavior, and expected latency. It also covers prerequisites (account, paid tier) and distinguishes from sibling tools. An agent has all necessary information to decide, invoke, and interpret results correctly. No critical aspect is missing.

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

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

Schema description coverage is 100% for both parameters, so the baseline is 3. The description adds value by elaborating on the depth parameter beyond schema: it explains 'standard' re-angles unanswered gaps, 'thorough' chases leads from the first pass, and notes that 'thorough' requires a paid plan — details not present in the schema. The question parameter is straightforward, but the depth parameter gets meaningful additional usage context. This warrants 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 states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources'. It clearly distinguishes from siblings by stating 'this is NOT open-web search' and explicitly naming ask_pipeworx as the alternative for single lookups and breaking news. The purpose is unambiguous and differentiated.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data', and when-not: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also conditions on account state: 'If you are not signed in, use ask_pipeworx instead'. Depth-specific guidance is given for 'standard' vs 'thorough'. All alternatives and exclusions are named.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed'. 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?

A single, information-dense paragraph. Every sentence adds value: purpose, when-to-use, examples, return format. Could be slightly more structured with bullet points, but very 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?

No output schema exists, so description must convey return format. It does: 'names, descriptions, full input schemas (with curated examples)'. Covers the essential context for a discovery tool with moderate complexity.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description adds value by explaining that 'query' accepts aliases and is a 'natural language description'. Does not repeat schema content but adds context.

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

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

States the tool's verb ('Find tools by describing the data or task') and resource ('tools'). Specifically positions it as the first call when many tools are available, distinguishing it from sibling tools that perform specific actions.

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 'Call this FIRST when you have many tools available and want to see the option set'. Provides a comprehensive list of example use cases (SEC filings, FDA drugs, etc.), giving clear when-to-use guidance.

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

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

Beyond annotations indicating read-only, open-world, and idempotent behavior, the description details the fan-out across multiple sources, specific return fields with URIs, and notes about data source sunset (USPTO PatentsView). This adds significant context for the agent.

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 rich but somewhat lengthy; however, it is well-structured with examples upfront, a clear directive, and a comprehensive list of returns. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Despite no output schema, the description thoroughly covers the tool's purpose, usage context, behavioral details, parameter constraints, and expected output composition. It is complete for the agent to make an informed invocation decision.

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, but the description enhances semantics by providing concrete examples (e.g., 'AAPL', '0000320193'), reiterating that names are not supported, and directing to resolve_entity as an alternative.

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

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

The description uses specific verbs and resources, listing concrete user query examples like 'Tell me about X' and 'research Acme.' It clearly distinguishes itself from the sibling tool 'resolve_entity' by noting that names are not supported, thereby clarifying its unique purpose.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack...') and when not to use it ('names not supported — use resolve_entity first'), providing clear guidance on 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 provide destructiveHint=true and idempotentHint=true. Description adds context like 'clear sensitive data' and is consistent. No contradictions.

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

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

Two sentences, zero waste. Every sentence adds value: purpose, usage guidance, and pairing advice.

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

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

For a simple tool with one parameter, no output schema, and good annotations, the description is complete. It covers purpose, usage, and pairing 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?

Only one parameter 'key' with schema description 'Memory key to delete.' Schema coverage is 100% so baseline of 3 is appropriate. Description does not add extra semantics 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 'Delete a previously stored memory by key.' The verb 'Delete' and resource 'memory by key' are specific. It distinguishes itself from siblings by noting 'Pair with remember and recall.'

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' No exclusions but provides clear context and pairing advice.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds value by detailing the process (fetches page, extracts content, outputs markdown) and mentions the output destination (site-root/llms.txt). 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 two sentences plus a bullet-like list of use cases, all front-loaded with the main action. Every sentence adds value, 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?

Given no output schema, the description adequately describes the output format (standard llms.txt markdown, single text blob) and input parameters. Complexity is low, and the description provides all necessary context for an agent to understand and invoke the tool.

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

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

Schema description coverage is 100% for both parameters. The description restates the URL purpose ("Full URL") but adds no new details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (fetch, extract, emit). It uniquely identifies the tool's purpose among siblings, though explicit sibling differentiation is minimal.

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 three concrete use cases (getting a client's site indexed, drafting for own project, auditing competitors). It implies when to use but does not explicitly exclude alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description complements by specifying return fields and optional parameter, but 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?

Two sentences, front-loaded with purpose, no filler. Efficient and to the point.

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

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

Given the tool's simplicity (1 optional param, no output schema), the description adequately covers purpose, returned data, and usage context.

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

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

Schema coverage is 100% with full parameter description. The description does not add additional context about the parameter beyond what schema provides, meeting baseline but not exceeding.

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 'List the caller's active subscriptions' with specific verb and resource, and enumerates returned fields (id, type, etc.). Distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool to review monitored subscriptions before adding more or to find an ID to cancel, providing clear guidance on when and why to use 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?

Despite annotations offering no hints (all false), the description fully discloses key behaviors: filing without an account returns a claim_token that can be used later to check resolution status, rate-limited to 5 per identifier per day, free with no quota impact, and that the team reads digests daily. This covers side effects and follow-up mechanics beyond what annotations provide.

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

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

Although the description is longer than average, every sentence carries distinct value: purpose, usage conditions, exclusions, claim-token workflow, rate limits, and quota impact. It is front-loaded with the core purpose and maintains logical flow 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?

The tool has moderate complexity (nested context object, no output schema), and the description covers the complete user journey: when to use, what to report, how to follow up via claim_token, rate limits, and impact. No return schema is needed since the description explains what the token does and how resolution status is retrieved.

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 substantial meaning: it explains the type categories with concrete examples, clarifies the claim_token usage flow (pass it later with no other arguments to read status), and advises on message specificity (1-2 sentences, which tool/pack). This goes far beyond the schema field descriptions.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback categories (bug, feature/data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by focusing on reporting issues to the team rather than querying information.

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

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

Provides explicit when-to-use guidance: for bugs, feature/data_gap, or praise. It also gives a clear exclusion: if the originating tool belongs to a different MCP server, file feedback with that server instead. Includes a practical rule for identifying Pipeworx tools and instructs users not to paste end-user prompts.

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 safety traits (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: data source ('CF analytics-engine'), privacy ('no PII'), output structure ('(pack, tool, count)'), and caching behavior ('Cached 5min-1h'). No contradictions.

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

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

The description is a single, well-structured paragraph that front-loads the action ('Returns...') and then lists use cases in a numbered format. Every sentence adds value with 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 tool with one optional parameter and no output schema, the description fully covers what the agent needs: what it returns, why to use it, how the data is derived, and caching. Annotations provide safety context.

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

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

Schema coverage is 100% with a clear enum. The description adds meaning beyond the schema by explaining the trade-off between window sizes ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description provides a specific verb ('Returns') and clearly states the resource: top tools, top packs, and total call volume. It distinguishes itself from siblings like `discover_tools` by focusing on what other AI agents are using, giving a unique purpose.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming popular tool, seeing alignment with agent needs). While it doesn't mention when not to use it or alternatives, the context is clear and sufficient for selection.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses detailed behavior: monotonicity checks, partition-sum checks, semantic anchor, partition filter, fill check with live order book depth. It warns about the overround at last-trade and advises not to trade when realizable_edge_pp ≤ 0. No annotation contradiction.

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

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

The description is detailed and covers all necessary aspects, but it is somewhat verbose. It includes many specifics that could be condensed without losing clarity. Nonetheless, it is well-structured and front-loaded with the main purpose.

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

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

Given the tool's complexity, the description fully explains the response structure (opportunities[], partition_check) and includes fill check logic. It also references related tools for customization, making it complete for an AI agent.

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

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

Although schema coverage is 100%, the description adds significant meaning: it explains that 'event' takes a slug like 'fed-decision-may-2026' and 'topic' takes a seed question like 'Fed rate decision'. It details the behavior for each parameter, including the trending_scan for no args.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three modes (no args, event, topic) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly instructs when to use each mode: 'Call with NO args for trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also mentions an alternative tool: 'For custom sizing use polymarket_fill_risk.'

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

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

The description provides extensive behavioral details beyond annotations: caching (1h at KV level), model families, edge calculations, tradeable-edge filters, and response structure with diagnostics. No contradiction with annotations (readOnlyHint, 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 well-structured with bold labels and logical sections. The density is justified by the tool's complexity, but it could be slightly more concise without losing key details.

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

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

Given the tool's complexity (9 parameters, no output schema), the description thoroughly covers response structure (by_segment, fed_candidates, _diagnostics) and explains how filters work. It is complete for an AI agent to understand and use the tool.

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

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

Schema coverage is 100%, and the description adds significant context: explains why min_kelly and min_partition_leg_kelly differ, notes Polymarket's fee structure, and clarifies slippage assumptions. This adds meaning beyond parameter names and basic descriptions.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement.

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

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

The description includes explicit usage guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains tradeable-edge knobs and diagnostics. While it doesn't explicitly state when not to use, the context clearly differentiates from 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 declare read-only, idempotent, non-destructive. Description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), decay computation, snapshot gaps, and limitations, all consistent 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?

Long but efficient: front-loaded with key question, then response fields, then limits. 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?

Without an output schema, the description fully details the return structure (tracked[], expired[], snapshot_dates[]) and edge cases (gaps, TTL, decay calculation). Complete for effective use.

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

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

Both parameters have schema descriptions (100% coverage). Description adds defaults, clamps, and the meaning of 'window' (snapshot family), providing extra value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering a specific trading question. It distinguishes from siblings like polymarket_edges by focusing on historical tracking.

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?

Describes when to use: to assess edge age and decay. Provides context on trade interpretation (fresh vs old edges) and limits (snapshot TTL, not intraday). Lacks explicit when-not-to-use or alternatives, but context is sufficient.

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

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

Annotations show read-only, idempotent, safe. Description adds beyond: walks order ladder, returns verdict (clean|degraded|cannot_fill), warns about forced directional risk, and explains partial basket fill consequences. 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?

Well-structured with clear sections (REQUIRES one of, SINGLE-MARKET, BASKET, USE THIS). Front-loaded with purpose. Slightly verbose but justified by complexity; every sentence adds value.

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

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

No output schema, but description enumerates return fields for both modes and explains the verdict and partial fill risks comprehensively. Complete given the tool's complexity.

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

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

Schema coverage 100%, but description adds meaning: explains size_usd interpretation for single-market vs basket, side default logic (auto from partition sum), and how parameters interact in the overall flow.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and contrasts single-market vs basket modes with specific return fields, distinguishing it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the risk of partial fills converting arb into directional positions.

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?

Rich behavioral disclosure beyond annotations: details response fields (compatibility_warning, temporal_alignment, skipped counters), explains when spreads are meaningless (non-equivalent bet shapes, misaligned time periods). No contradiction with readOnlyHint/idempotentHint.

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

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

Well-structured with clear sections and front-loaded purpose. Slightly lengthy but each sentence adds value for a complex tool. Could be tightened, but still effective.

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

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

Compensates for lack of output schema by describing response fields comprehensively, covering edge cases (compatibility warnings, temporal alignment, skipped comparisons). Complete given tool complexity.

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

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

Schema coverage 100%, but description adds significant context: explains interaction between topic and explicit parameters, lists all 10 topic shortcuts with semantics, and clarifies override 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?

Clearly describes cross-venue spread tool comparing Kalshi and Polymarket. Distinguishes from siblings like polymarket_arbitrage by focusing on same-question pricing differences across venues.

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

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

Explains two modes (topic shortcuts vs explicit event tickers) and provides caution that most pre-mapped topics may not be tradeable. However, does not explicitly direct to alternatives when this tool is inappropriate.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral context: scoping to an identifier and the listing behavior when key is omitted. 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 concise (3 sentences), front-loaded with the main action, and provides all necessary context without redundancy. Every sentence serves a purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers its functionality, usage context, scoping, and relationship to sibling tools. 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?

Input schema coverage is 100% and the schema description for the only parameter (key) is already informative. The description reinforces but does not add new parameter-level details beyond what the schema 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 uses specific verbs ('retrieve', 'list') and clearly identifies the resource ('value previously saved via remember'). It distinguishes from siblings by explaining that omitting the key lists all saved keys, and mentions pairing with 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?

The description explains the purpose ('look up context the agent stored earlier') and the alternative behaviors (list all vs. retrieve specific). It references siblings (remember, forget) for complementary actions. No explicit 'when not to use' is given, but context is clear enough for correct tool selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds important behavioral detail: mark_read:true flags events as read, affecting future calls. This goes beyond annotations but could mention idempotency or rate limits.

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 concise paragraph with front-loaded purpose. Every sentence adds unique value—return fields, filters, mark_read behavior, and alternative endpoint. No wasted words.

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

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

Given 5 optional parameters, no output schema, and rich schema descriptions, the description effectively covers return fields and the mark_read side effect. Mentioning the alternative endpoint improves completeness. Minor missing: explicit pagination or error handling.

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 parameters are documented. The description adds extra context: examples for type (e.g., 'sec_8k'), clarifies mark_read effect ('so the next call only shows newer ones'), and unread_only behavior. This exceeds baseline 3.

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

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

The description clearly states the tool retrieves recent alerts from the subscription feed, specifying return fields (source, citation_uri, payload) and filters (type, since). It distinguishes from siblings like list_subscriptions by focusing on pulled events rather than metadata.

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 that polling works fine and notes an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool versus sibling tools like recent_changes 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 already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral details: the tool fans out to multiple sources, has a fallback mechanism (GDELT→GNews), handles rate limits, and soft-fails for patents. This exceeds what annotations provide.

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

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

The description is detailed but well-structured, starting with example queries. Each sentence adds meaningful information without redundancy. While slightly long, it remains focused and front-loaded.

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

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

Given the tool's complexity (three data sources, fallbacks, parameter formats) and the absence of an output schema, the description adequately covers return structure (grouped changes, total count, citation URIs) and usage context. Minor gaps: error behavior beyond rate limiting is not detailed.

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 further semantic value: clarifies 'since' accepts ISO dates or relative shorthand with examples, and 'value' can be ticker or CIK. This enhances understanding 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 the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from sibling tool entity_profile, which provides static profiles.

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

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

The description provides explicit when-to-use examples ('What's new with X' etc.) and directs to entity_profile for static profile queries. However, it doesn't explicitly state when not to use this tool (e.g., for real-time data or non-company entities), though the 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?

Discloses persistence details (scoped by identifier, 24-hour retention for anonymous) beyond annotations. Annotations already indicate idempotent and non-destructive, so description adds context without contradiction.

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

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

Front-loaded with purpose, then details. Compact but covers all necessary aspects. Could be slightly tighter, but 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?

Complete for a simple key-value store: explains purpose, when, how, persistence, and pairing with siblings. No output schema needed, and description covers all relevant context.

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

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

Schema coverage is 100%, and description adds concrete examples for keys (subject_property, target_ticker) and values (findings, addresses), enriching 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?

Provides specific verb ('Save data') and resource ('data the agent will need to reuse later'), with clear examples (ticker, address, preference). Distinguishes from siblings 'recall' and 'forget' by naming them.

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

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

Clearly states when to use ('when you discover something worth carrying forward') and pairs with recall/forget. Does not explicitly state when not to use, but usage context is well-defined.

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 substantial behavioral context beyond the annotations: it cascades through multiple lookup endpoints, degrades gracefully when external services (GLEIF/OpenFIGI) are unavailable, explicitly lists unresolved identifiers, and labels identifiers by source. This gives the agent a clear picture of what happens during execution, complementing the readOnlyHint and idempotentHint.

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

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

The description is long, but it's well-organized and every sentence contributes meaning. It starts with example queries that quickly convey the tool's function, then provides structured details on supported types and behaviors. While not as concise as a two-sentence description, the length is justified by the tool's complexity.

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

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

Given the tool's complexity and lack of an output schema, the description is highly complete. It covers return values (CIK, ticker, LEI, FIGI, etc.), unresolved handling, input variations, graceful degradation, and internal cascading. It also explains edge cases like ISIN-to-LEI mapping, ensuring the agent understands what to expect in a wide range of scenarios.

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

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

The schema already covers both parameters, but the description adds extra meaning: it specifies that 'value' for company can also accept ISIN (not listed in the schema), provides concrete examples ('AAPL', '0000320193', 'ozempic'), and explains how an ISIN resolves to a legal entity. This enhances the schema's description, so the score is above baseline.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It uses specific verbs like 'resolve' and identifies the resource (names → IDs), and it distinguishes itself from siblings by emphasizing that it provides input for other tools. The examples and supported types further clarify its scope.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups, implying it is the preferred tool for ID resolution. The supported types and input formats give clear context for when to use 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=true, idempotentHint=true, destructiveHint=false, so no safety concerns. The description adds that the tool probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density. It does not reveal any hidden side effects or caveats beyond the optional _apiKey requirement.

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 serving a distinct purpose: function, mechanism, and use case. No redundant words or filler. Information is front-loaded with the primary 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?

Given no output schema, the description adequately outlines return value (ranked list with score, confidence, signal density). Parameter usage is fully explained. Annotations cover safety and other hints. Nothing crucial is missing for an AI agent to correctly invoke this tool.

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

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

With 100% schema description coverage, the description still adds value: it explains that the first entity is treated as the 'subject' for narrative, that 'models' has a free default and anthropic requires an API key, and that 'context' disambiguates common names. This goes beyond the parameter descriptions.

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

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

The description uses specific verbs ('compare', 'scans', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (likely different comparison) by specifying the use of ai_visibility_check internally and focusing on AI presence ranking.

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 the tool is for competitive AI-marketing audits and gives a concrete example question. It does not explicitly list when not to use it or name alternatives like 'compare_entities', but the context strongly implies single-entity checks should use 'ai_visibility_check'.

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, etc.), the description discloses partial failure behavior: bundlephobia first measurement may take 5-30 seconds, and sources_failed will list it if timed out. It also lists the exact fields returned, giving full transparency on what the agent gets.

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 packed with information but remains a single coherent paragraph. It front-loads the composite check purpose, then expands logically. The minor deduction is for slight length; it could be broken into two sentences for easier scanning, but it is still 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?

With no output schema, the description fully explains the return structure (summary fields, advisories, links, alternatives) and handles edge cases like partial failures and version defaults. It covers all necessary context 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?

The schema covers both parameters, but the description adds: scoped packages are accepted (not in schema description), and version defaults to latest when omitted. This adds 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 the composite check for whether to add an npm package, lists the data sources (deps.dev and bundlephobia), and specifies the return elements (summary block, advisories, links, alternative versions). It immediately distinguishes itself from sibling tools like validate_claim or deep_research by defining its specific function.

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

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

Provides explicit when-to-use guidance: inquiries about safety, popularity, size, or cost of adding a package. Also specifies the ecosystem limitation (NPM only v1) and directs users to deps.dev:version directly for other ecosystems, which is a clear alternative.

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

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

Description adds significant detail beyond annotations: uses BGE-base-en embeddings + cosine over 500-char windows, 200K char cap with truncation flag, and passages include offsets for verification. Annotations already show read-only, idempotent, etc., but the description enriches understanding.

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

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

Concise, front-loaded with core purpose. Each sentence adds value: purpose, usage scenario, technical details. 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?

Without output schema, description covers return values (passages with offsets and similarity scores). Also explains technical details (embedding, windowing, character limit). Complete for a search tool.

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

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

Schema coverage is 100%, but description adds value: explains 'text' as document to search, 'query' as natural-language with examples, and 'limit' as max passages. Also mentions truncation behavior for text.

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

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

Clearly states it performs semantic search inside a fetched record, with examples like SEC 10-K or article. It distinguishes from siblings by noting it works on provided text, but does not explicitly differentiate from other search tools like ask_pipeworx.

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

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

Explicitly says when to use: when the record is too big for the prompt, to save context. Mentions pairing with ask_pipeworx_grounded. Does not specify when not to use or list alternatives, but the usage 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?

The description contradicts the idempotentHint annotation: it says each call creates a new subscription ('Returns the new subscription id'), implying non-idempotent behavior, while annotation claims idempotentHint=true.

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?

Comprehensive but slightly verbose; good front-loading with purpose and requirements, but delivery channel details could be more condensed. Still earns its sentences.

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

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

Covers all essential aspects: supported types with examples, delivery methods, requirements, limitations. No output schema but notes return value. Complete for a creation tool with nested options.

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 rich context: examples for each type, structure of params, and detailed delivery channel behavior including webhook signing and auto-disable. Much more than schema alone.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns a subscription ID, and distinguishes itself from siblings like list_subscriptions and unsubscribe by being about creation.

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

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

Explicitly states when to use (create subscriptions), prerequisites (Pipeworx OAuth account, not for anonymous/BYO), and limitations (SMS verification, 10/day cap). Implicitly contrasts with list/unsubscribe 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 it read-only, open-world, idempotent, and non-destructive. The description adds useful context about return format (category-bucketed example questions) and meta-tools, without contradicting annotations.

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

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

The description is a single sentence that front-loads the common queries and packs all necessary information efficiently. Slightly long but every part 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, the description fully explains what the tool returns (category-bucketed examples with tool+argument shapes). Parameter is clearly explained, and annotations cover safety. Complete for an informational onboarding tool.

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

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

Schema coverage is 100%, but the description adds value by explaining the topic parameter's usage ('call with no arguments for the full spread') and listing possible values, going beyond the schema's description.

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

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

The description clearly states the tool's purpose as an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes, and distinguishes it from siblings like ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you', and explains optional topic filtering. Lacks explicit '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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, effectively communicating safety. The description adds only that it 'gets details,' which is consistent but does not elaborate on authentication requirements or rate limits beyond the schema.

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, concise sentence that directly states the tool's purpose. No extraneous information is included.

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 operation with complete annotations and an output schema (exists but not shown), the description is adequate. It could mention that authentication credentials are required, but those are already listed in the schema.

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

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

Schema coverage is 100%, with each parameter already described (e.g., sid: 'Message SID (starts with SM...)'). The description emphasizes the sid parameter but adds no new meaning beyond the schema.

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

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

The description clearly states 'Get details of a specific Twilio message by its SID,' specifying the verb (Get), resource (Twilio message), and identifier (SID). This distinguishes it from siblings like twilio_list_messages or twilio_send_sms.

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 when you have a message SID and need details. The presence of sibling twilio_list_messages provides context for when to use listing vs. single retrieval, but no explicit when-not-to-use or alternatives are given.

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, idempotentHint, destructiveHint. Description adds that calls are 'recent' and returns fields. No additional behavioral traits like pagination, sorting, or region-specific issues disclosed. Description is consistent 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?

Two efficient sentences, zero waste, front-loaded with purpose and key output info.

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 high schema coverage and an output schema present, the description is fairly complete. It covers the basic return fields and purpose, though it could mention pagination or sorting constraints for a more thorough specification.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add extra meaning beyond the schema for parameters; it only summarizes output fields. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'list' and resource 'recent phone calls' and lists returned fields (call SID, status, duration, direction). This distinguishes it from siblings like twilio_make_call and twilio_list_messages.

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?

Implicit usage is clear for listing calls, but no explicit guidance on when to use this tool versus alternatives (e.g., twilio_get_message) or any preconditions. No 'when not to use' stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, providing a strong safety profile. The description adds that it lists recent messages and supports filtering, but doesn't elaborate on what 'recent' means or any rate limits, so it adds only minor context 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 two sentences long, immediately states the core function, and includes key capabilities without extra words. It earns its place efficiently.

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

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

Given that an output schema exists (documenting return values) and the tool is a simple read-only list operation, the description covers the main points: listing, filtering, pagination. Missing details like sorting or default behavior are minor given the overall clarity.

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

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

The input schema has 100% description coverage for all parameters, so the baseline is 3. The description repeats that filtering by to/from and pagination exist, but adds no new meaning beyond the schema's own descriptions.

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

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

The description clearly states the tool lists recent SMS/MMS messages, which is a specific verb+resource combination. It naturally distinguishes from siblings like twilio_send_sms and twilio_get_message by focusing on listing SMS/MMS.

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 mentions filtering and pagination, implying typical use cases, but does not explicitly contrast with alternatives (e.g., twilio_get_message for single message retrieval), leaving the agent to infer when to use this tool.

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

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

The description contradicts the annotation readOnlyHint=true by stating it initiates a call (a mutation). It does not disclose side effects like cost or API call consequences. This is a serious inconsistency.

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

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

Two sentences with no wasted words. First sentence states the action, second adds a critical requirement. Front-loaded and efficient.

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

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

Despite an output schema, the description omits crucial behavioral context like authentication setup, error handling, or cost implications. The mismatch between description and schema (application SID) makes it incomplete.

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

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

Schema coverage is 100%, so baseline is 3, but the description introduces 'application SID' as an alternative not present in the schema, potentially confusing agents. It adds minimal value beyond the schema.

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

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

The description clearly states the action 'Initiate a phone call via Twilio' and distinguishes it from sibling tools like twilio_send_sms and twilio_list_calls. It mentions a key requirement (TwiML URL/application SID), providing specific 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?

It implies when to use (making a call) but does not explicitly compare with alternatives. The requirement is stated, but no guidance on when not to use or prerequisites beyond the schema.

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 mutation (readOnlyHint=false), idempotency hint (idempotentHint=true), and non-destructive nature. The description adds the return value (SID and status), which is useful but does not address rate limits, costs, or clarification of idempotency. Thus, it provides some value beyond annotations.

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

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

The description is a single sentence of 10 words, front-loading the main purpose and return value. Every word is necessary; no 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?

The description adequately covers the main purpose and return format. With an output schema available (as per context signals), it complements the schema well. It could mention character limits or authentication requirements, but the schema already covers those.

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

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

Schema description coverage is 100%, so the schema already documents all parameters with descriptions. The tool description does not add new semantic meaning about the parameters beyond what is already in the schema.

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

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

The description clearly states the action 'Send an SMS message via Twilio' and the return value 'Returns the message SID and status.' This distinguishes it from sibling tools like twilio_get_message or twilio_list_messages, which are for reading or listing messages.

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 tool's purpose is clear enough that an agent would know when to use it (sending SMS) versus alternatives (retrieving messages or making calls). However, there is no explicit guidance on when not to use it or mention of 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), description clarifies soft-delete behavior: row is deactivated not deleted, and historical events remain accessible via recent_alerts. 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?

Two sentences, no fluff, front-loaded with action and resource. Every sentence adds value.

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

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

Tool is simple with single parameter, no output schema; description covers purpose, ownership, and side effects adequately for an agent to invoke it correctly.

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

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

Schema already describes the id parameter as 'Subscription id (uuid) returned by subscribe' with 100% coverage; description adds no additional semantics beyond mentioning 'by id', so baseline 3 is appropriate.

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

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

Description clearly states the verb 'Cancel' and resource 'subscription by id', distinguishing it from sibling tools like subscribe (create) and list_subscriptions (list).

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?

Ownership enforcement is stated ('you can only cancel your own subscriptions'), which provides a usage constraint but does not explicitly direct when to use this tool over alternatives 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 already declare read-only/idempotent/open-world, and the description adds critical behavioral detail: it explains the two processing pipelines, defines all six verdict values, and crucially warns that `could_not_verify` indicates a check failure (with `verification_error`) and must not be treated as evidence. This goes far beyond the annotation hints.

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 most but every section earns its place: query examples, routing logic, verdict semantics, and caller caveats. The 'Replaces 4–6 sequential calls' is a minor extra, but the overall structure is clear and front-loaded with the core purpose.

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

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

For a tool with no output schema, the description fully specifies the return shape (verdict, actual value, pipeworx:// citation, reasoning), enumerates all verdict values, and explains ambiguous outcomes like unsupported vs. could_not_verify. It also describes internal routing, making it self-contained and actionable.

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%; both `claim` and `tolerance_pct` have detailed descriptions with examples. The tool description does not introduce additional parameter semantics beyond mentioning 'exact percent-delta math,' so it neither adds nor subtracts value; 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 immediately establishes the tool as a natural-language claim verifier with clear examples ('fact check', 'is it true that…'), and explicitly states its function: 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by naming the structured SEC EDGAR path for financial claims and the grounded pipeline for all others, plus the specific verdict vocabulary.

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 when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the two routing paths (financial vs. other claims), and notes it replaces 4–6 sequential calls, but it does not explicitly name alternative tools or state when not to use it.

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