Wikiquote

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by specifying the default model, BYO key requirement, and return structure ({score, confidence, signals, raw_response}). 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 three sentences, front-loaded with the main action, and every sentence adds value. 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?

With no output schema, the description adequately describes return structure (per-model + combined). It covers parameters, behavior, and output. Could mention rate limits or cost implications but not necessary for completeness.

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

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

Schema description coverage is 100%, baseline 3. The description adds meaning: explains how to omit models for default, the purpose of _apiKey (passed through to Anthropic), and context for disambiguation. This exceeds 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 probes LLMs and scores visibility (0-100) per model, with specific examples. It does not explicitly differentiate from sibling tools like 'scan_competitor_ai_presence', but the action is distinct enough.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') but does not provide explicit when-to-use vs alternatives or exclusions. Sibling tools exist but no guidance on choosing.

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

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

Annotations already indicate this is read-only, idempotent, open-world, and non-destructive, so the description does not need to repeat safety information. It usefully adds behavioral context: the tool routes to other tools, fills arguments, returns structured answers with pipeworx:// citation URIs, works on every tier, and makes a single fast call. This goes beyond the annotations and helps set expectations for the response format.

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 typical, but it is well-structured and front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'). It efficiently covers what the tool does, when to use it, examples, and alternatives. Minor redundancy exists ('even if web search could also answer it' restates the preference), but the extra length is justified by the tool's role as a default entry 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?

For a tool with no output schema, the description is remarkably complete: it explains the tool's routing behavior, supported data domains, citation format, speed, tier availability, example usage, and when to escalate to sibling tools. There are no significant gaps in understanding what the tool returns or how to invoke it.

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

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

The schema already fully describes all six parameters (all aliases for 'question'), so baseline is met. The description adds value with concrete example questions like 'current US unemployment rate' and 'Apple's latest 10-K', showing what kinds of natural-language inputs are appropriate and clarifying expected question style beyond schema descriptions.

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

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

The description clearly states the tool's function: route a natural-language question to the right source among thousands and return a structured, cited answer. It explicitly positions itself as the default entry point over web search, and distinguishes itself from key siblings like ask_pipeworx_grounded and deep_research, making its purpose unmistakable.

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

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

The description gives explicit guidance on when to use the tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also provides concrete example queries and notes it handles breaking news, making selection easy.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the experimental nature: candidate routing improvements, no active candidate as of 2026-07-26, and that it's a full working router. This context is valuable beyond the annotations.

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

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

The description is reasonably concise, with sentences that each add information: beta status, current candidate state, usage instruction, and caveat. It's slightly longer than necessary but not wasteful.

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 a universal router, the description covers what it is, current behavior, usage, and relationship to the stable version. It references the response shape matching ask_pipeworx, which is sufficient given no output schema.

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

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

The schema provides 100% coverage with descriptions for all six parameters, including aliases. The description adds only that arguments are identical to ask_pipeworx, which is already implied. 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 this is the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge, making its purpose obvious.

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

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

It explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing and mentions results are compared against the stable router, implying the alternative. However, it could be more explicit about when to prefer the stable version.

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

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

Annotations declare readOnly/idempotent/openWorld, but the description adds significant behavioral context: the refusal_reason enum values, the 'uses ONLY what the tool result contains' constraint, and the extra LLM call cost. This goes well beyond the annotations and fully discloses the tool's operational behavior.

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

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

The description is dense but every sentence serves a purpose: what it does, how it behaves, return format, refusal reasons, when to use, and cost tradeoff. It is front-loaded with the key differentiator and remains structured and scannable.

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 explicitly documents the return object and all refusal_reason values, which is critical for the agent to handle both success and failure. Combined with the use-case guidance and cost note, there is nothing missing for a single-parameter 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?

All 6 parameters are aliases for the single 'question' parameter, and the schema already describes each alias and states that 'question' accepts natural language. The description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a hallucination-resistant answer mode that extracts answers using ONLY the tool result, distinguishing it from the sibling ask_pipeworx. It names the specific return structure and refusal behavior, making the purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff (one extra LLM call), providing clear decision guidance.

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

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

The description discloses extensive behavioral details beyond annotations: resolution contract (market_match_confidence, alternatives, suggestions), parent event extractor, news fallback fields, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread market warnings, and resolution-rule risk (cancellation rule analysis). This fully compensates for the lack of output schema and adds significant value.

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 very long and dense, with many examples and edge cases. It is well-structured with sections (classifiers, fan-out examples, response shapes, etc.), but could be more concise. The length may hinder quick parsing by an agent.

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

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

Given the tool's complexity (3 params, no output schema), the description covers inputs, expected outputs, edge cases (low-confidence, closed markets, wide spreads), resolution rules, and safety mechanisms. It is comprehensive and leaves little 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?

Although schema coverage is 100%, the description adds critical context: 'market' can be slug, URL, or question text; 'depth' defaults to thorough; 'include_raw' explains default false and when to set true. This meaningfully extends the schema definitions.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output structure (evidence packet + market-vs-model comparison). This distinguishes it from siblings like 'polymarket_edges' or 'deep_research' which likely have different scopes.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifiers and fan-out examples. It does not explicitly state when not to use, but given the specificity, it is clear enough for an agent to decide.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive. The description adds extra behavioral context: it pulls from SEC EDGAR/XBRL for companies and FAERS for drugs, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. No contradictions.

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

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

The description is front-loaded with the essential purpose and trigger phrases, then provides concise details. Every sentence adds unique value; there is no redundancy or fluff. It is efficient despite its length.

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

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

There is no output schema, but the description explains the output format (paired data + citation URIs) and sorting behavior. It does not mention error conditions or rate limits, but annotations cover safety. For a tool replacing many lookups, the context is sufficient.

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

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

Schema coverage is 100% and describes type and values clearly. The description adds meaning by explaining what each type pulls (e.g., latest 10-K data for companies, adverse-event counts for drugs), enhancing the schema's context. It doesn't just repeat schema info.

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

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

The description starts with natural language trigger phrases and clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sequential lookups and specifies what each entity type returns, making the tool's purpose immediately clear.

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,' providing clear when-to-use guidance. However, it does not explicitly mention alternatives like 'entity_profile' for single entity lookups, which would strengthen the guidance further.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses account/auth requirements, expected latency (15-90s), output structure (gaps[], contradictions[], hop field, citation_uri), semantic excerpting of large records, and fallback behavior for out-of-catalog topics. This adds substantial operational context that annotations alone do not provide, with 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?

Although the description is long, every sentence earns its place: prerequisites, fallback, core definition, use cases, technical behaviors, and timing. The structure is logical and front-loaded, starting with the most critical prerequisite (account) and then layering details. For a tool of this complexity, the size is appropriate and well-organized.

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

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

With no output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[]). It also covers account/auth, latency, scope limitations, and when to choose alternatives. This is exceptionally complete for a complex tool.

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

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

The input schema fully documents both parameters, with depth's enum description covering facet counts, hop behavior, and contradictions scan. The tool description repeats this information but adds no new parameter-level meaning beyond what the schema already provides. With 100% schema coverage, 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 clearly states it performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, and explicitly distinguishes itself from open-web search and from ask_pipeworx for single lookups. This makes the tool's purpose and scope unmistakable and differentiates it from sibling tools.

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

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

Provides explicit usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also instructs to use ask_pipeworx if not signed in. This is comprehensive when-to-use guidance with named alternatives.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that each result is ready to call directly with full schemas and curated examples, which is consistent and adds value beyond annotations.

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

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

Two sentences, front-loaded with purpose then usage guidance. Could be more structured but is efficient and clear.

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

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

Despite no output schema, the description explains what the output contains (tools with names, descriptions, schemas, examples). It covers the complexity of discovery and provides context for the limit parameter.

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

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

Schema coverage is 100% (baseline 3). The description adds context: query is a natural language description, and provides examples. It also notes aliases, which are already in schema, but the extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and explains it returns top-N relevant tools with full schemas, distinguishing it from siblings like 'search'.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies 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?

Descriptions aligns with annotations (read-only, idempotent, non-destructive) and adds significant detail: fan-out across multiple data sources, returned fields (cik, filings, fundamentals, patents, news, LEI), and caveats like patent soft-fail due to API sunset.

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 fairly long but front-loaded with usage examples and purpose. Each sentence adds value; however, it could be slightly more structured (e.g., bullet points for returned fields). 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 no output schema, description adequately covers return structure and limitations (patent sunset, news fallback). Missing details like error handling for invalid ticker, but overall sufficient for a complex multi-source tool with full annotations.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by clarifying value parameter with examples (ticker vs zero-padded CIK) and repeating the name restriction, which is more explicit than schema. Minor extra context beyond schema.

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

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

Description starts with concrete user queries like 'Tell me about X' and 'research Acme', clearly states it returns a full cross-source profile of a US public company, and distinguishes itself as the preferred tool over chaining single-pack queries for holistic views.

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 to use this tool when user asks for a holistic view, advises against chaining single-pack lookups, and specifies to pass ticker or CIK (not names) with alternative (resolve_entity) for names. Clear 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?

Description confirms delete operation, aligning with destructiveHint=true. Adds context about clearing sensitive data, beyond annotations.

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

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

Two focused sentences with action verb upfront, minimal and complete.

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?

Sufficient for a simple delete operation: one required param, no output schema needed, guidelines provided.

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 covers the single parameter 'key' with description 'Memory key to delete'. Description adds no additional semantic value.

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

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

Explicit verb 'Delete' and resource 'memory' with 'by key' clarifying scope. Mentions sibling tools 'remember' and 'recall', distinguishing its purpose.

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

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

Explicitly states when to use: stale context, task done, clear sensitive data. Names alternatives to pair with (remember, recall).

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 nature. The description adds behavioral steps: HTTP fetch, extraction of metadata, and standard format emission. It does not contradict annotations and usefully enriches the agent's understanding of what happens.

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 three dense sentences with no filler. The first sentence states the core action, the second summarizes the workflow, and the third lists explicit use cases. Every sentence adds value, and the structure is 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?

No output schema exists, but the description explains the output is a 'single text blob in standard llms.txt markdown format.' For a simple tool generating a well-known format, this is sufficient. It does not discuss errors, rate limits, or page size limits, but the 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 description coverage is 100%, so baseline is 3. The description provides additional context: 'Full URL of the site to summarize' clarifies the scope, and mention of 'key links' connects to the max_links purpose. It does not add syntax details but gives usage motivation beyond the schema.

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

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

The description uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource ('llms.txt file') and scope ('for any URL'). It distinguishes from siblings by focusing on a unique output format and use case (AI indexing), which is not shared by nearby tools like 'scan_competitor_ai_presence'.

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

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

The description explicitly lists three concrete use cases (client site indexing, personal projects, competitor auditing). While it does not state when to avoid using the tool, the sibling list is large and the tool's purpose is narrow enough that the intended context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds return fields and the effect of the include_inactive parameter, but does not add behavioral context beyond what annotations and schema 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?

Two sentences: first defines purpose and output, second provides usage context. No unnecessary words, perfectly 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 simplicity (one optional parameter, no output schema, strong annotations), the description sufficiently covers what the tool does, what it returns, and when to use it. Minor absence of mention about scoping or limitations.

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

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

With 100% schema coverage, the baseline is 3. Description does not add new semantics for the include_inactive parameter beyond its schema description.

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

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

Description uses specific verb 'List' and resource 'caller's active subscriptions', and lists return fields. It clearly distinguishes from sibling tools subscribe and unsubscribe by stating it's for reviewing existing subscriptions.

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

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

Description explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel'. There is no 'when not to' but the context is clear given sibling tools.

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

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

Discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact, and return behavior ('Filing without an account returns a claim_token'). Annotations are all false, so description carries the full burden, and it meets it thoroughly with operational and post-submission details.

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

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

The description is long but every sentence adds crucial operational detail — scope boundaries, claim_token flow, rate limits, and roadmap impact. The opening sentence front-loads the purpose; no wasted words or redundancy.

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

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

For a 4-param tool with no output schema and all-false annotations, the description covers purpose, usage scenarios, scope restrictions, follow-up mechanism, and operational constraints. It sufficiently prepares an agent to invoke the tool correctly and understand the expected flow.

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 has 100% coverage with descriptions for all parameters. Description adds real-world context to `type`, `context`, and `claim_token` — e.g., explaining the claim_token round-trip process and the precise content expectations for `message`. This enriches the schema's bare descriptions, but a bit more on the exact format of `context` could be added.

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes from siblings like ask_pipeworx and discover_tools by focusing on reporting bugs, features, data gaps, and praise. The title also reinforces the purpose.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Provides exclusions: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' Also instructs on content guidelines: 'don't paste the end-user's prompt.'

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

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

Annotations already declare readOnly, openWorld, idempotent hints. Description adds value: self-aggregating signal from CF analytics, no PII, caching details (5min-1h). 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?

Description is a single paragraph, front-loaded with main output, then use cases listed with numbers, ending with caching details. Every sentence contributes 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?

Tool is simple (1 optional param, no output schema). Description covers return values, use cases, caching, and data source. Lacks output format details but adequate given no output schema.

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

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

Schema coverage 100% with window enum and description. Baseline 3. Description adds minimal extra meaning beyond schema (window length implications). Does not significantly enhance parameter understanding.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a window. The verb 'returns' and resource are specific. It distinguishes from siblings by focusing on AI agent call patterns, unique among listed tools.

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

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

The description enumerates three explicit use cases (discovering hot data, confirming canonical tool, checking alignment). It also explains window implication (short for hot, long for steady-state). Does not mention when not to use, but scenarios cover most needs.

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

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

The description discloses extensive behavioral details beyond annotations: partition check logic (sum of YES prices ≈1, thresholds), semantic anchor for cross-event, partition filter for placeholders, and fill check against live CLOB depth. All annotations (readOnlyHint, etc.) are respected and not contradicted.

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

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

The description is dense but well-structured, front-loading the core purpose and modes. It is longer than typical but every sentence adds necessary behavioral context for a complex arbitrage tool. Minor redundancy (e.g., 'trending_scan' clarified twice) prevents a perfect score.

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

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

For a complex tool with two modes and no output schema, the description thoroughly explains response structure (opportunities[], partition_check, fill check fields) and edge cases (cross-event similarity, placeholder filtering). It leaves no critical gaps for an agent to interpret the output.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning: what a slug looks like ('fed-decision-may-2026'), that full URLs are accepted for event, and how the topic parameter triggers cross-event scanning with example seed questions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_fill_risk by specifying that it scans for arbitrage, while others handle custom sizing or edge tracking. The three modes (no args, event, topic) are explicitly described.

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

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

The description provides explicit guidance: no args for trending scan, event for single-market analysis, topic for cross-event scanning. It recommends 'event' for specific markets and warns not to trade when fill check shows negative realizable edge. Alternatives like polymarket_fill_risk are mentioned for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond by detailing caching (1h at KV level), response structure (by_segment, fed_candidates, _diagnostics), edge computation (net of slippage, 24h-move warning), and model families. There is no contradiction with annotations.

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

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

The description is information-dense and front-loads the purpose, but it is very verbose, with detailed model explanations (e.g., lognormal barrier, GDELT ratios) that may overwhelm agents. While well-structured into segments and knobs, it would benefit from tighter prose. A 'less is more' approach could improve clarity.

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

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

Given the tool's complexity (9 parameters, 3 segments, no output schema), the description is remarkably complete. It explains response shape (top-level fields, diagnostics), caching, edge cases (empty segments, Fed bets), and knob interactions. It compensates for lack of output schema by detailing the return structure thoroughly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial value for every parameter: explains defaults (e.g., limit=10, window='1wk'), provides context (slippage_pp explains Polymarket fees and suggests adjustments), and clarifies edge cases (min_partition_leg_kelly explains why min_kelly doesn't filter partitions). This far exceeds the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It identifies the specific use case ('what should I bet on today') and distinguishes from siblings by detailing three unique response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) not present in related tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (to discover opportunities without paging hundreds of markets) and provides guidance on knobs like min_liquidity, max_spread_pp, and min_partition_leg_kelly. It notes that Fed bets are excluded from ranking and why. However, it does not explicitly state when to use sibling tools like polymarket_arbitrage or polymarket_edge_tracker, which would improve clarity.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds rich behavioral context: response structure (tracked, expired, snapshot_dates), decay computation details, meaning of signs in edge_pp_net, data gap handling, and TTL limits. No contradiction found.

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 a clear central question, then explains response fields and limits. Front-loaded with key purpose. Somewhat verbose but each sentence adds value.

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

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

Despite no output schema, the description thoroughly explains all three response arrays and their contents, including edge cases like gaps and TTL. Sufficient for understanding the tool's behavior and output.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds default values and clarifies clamp range for days. While helpful, it doesn't add substantial meaning beyond what's 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?

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Answers the core question 'how long has this edge existed and is it shrinking?'. However, it doesn't explicitly differentiate from sibling tool polymarket_edges, though it implies being an analytical layer.

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

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

Provides context about when to use (comparing fresh vs. old edges). Mentions limits (60-day TTL, snapshot start date). But lacks explicit guidance on when not to use or alternatives to consider.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: walks the ladder, returns specific fields, basket fill risks (thin_legs, forced_directional_risk), and warns about partial fills converting arb into unhedged directional position. No contradiction with annotations.

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

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

The description is well-structured with mode sections (SINGLE-MARKET, BASKET) and front-loads the core purpose. While it is relatively long, every sentence adds value given the tool's complexity. Minor room for tightening, but overall efficient.

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

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

No output schema exists, so the description bears the full burden of explaining return values. It thoroughly describes both modes' outputs (top_of_book, vwap_fill_price, slippage_pp for single-market; theoretical_sum, realizable_sum, profit_usd, per-leg detail for basket) and covers edge cases like thin_legs and forced_directional_risk. Complete for a tool of this complexity.

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

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

Schema coverage is 100% (each parameter has a description). The description adds meaning beyond the schema: e.g., size_usd is explained as 'max spend on buys, target proceeds on sells' for single-market and 'settlement notional — shares per leg' for basket; side default behavior is explained. It adds context without redundancy.

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 the tool's purpose clearly: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly tells the agent to use this before polymarket_arbitrage or polymarket_edges, differentiating it from siblings.

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

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

The description explicitly says when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills convert arb to directional) and provides prerequisites ('REQUIRES one of market or event').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: safety fields (compatibility_warning, temporal_alignment), skipped counters, and the note that real spreads are rare. 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 detailed but somewhat verbose. It uses sentence-case keywords for structure, which helps readability. However, it could be more concise by moving some explanatory details to a separate section. The length is justified by the complexity, but there is room for trimming.

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

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

Given no output schema, the description comprehensively explains the response format: leg-by-leg prices, top_spreads_pp, compatibility_warning conditions, temporal_alignment, and skipped counters. This leaves minimal ambiguity for an AI agent to understand what the tool returns.

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 value by explaining the two modes (topic overrides explicit fields), providing example values, and clarifying that topic auto-fetches matching events. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on a single question across venues, not arbitrage across questions.

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

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

The description provides explicit usage modes (topic shortcuts and explicit pairings) and explains when compatibility_warning fires, indicating when spreads are not meaningful. It also warns that most pre-mapped topics return warnings today, setting expectations. However, it does not explicitly list when NOT to use the tool, such as when only one venue has the event, though this is implied.

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

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

Adds context beyond annotations: explains the source (English Wikiquote) and locale behavior for non-English 'lang' values. 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?

Single sentence with no fluff. Key information front-loaded: 'Daily featured quote' with parenthetical detail about locale.

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?

Sufficient given simplicity (1 optional param, read-only, output schema exists). Could mention return format but output schema handles that.

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 parameter 'lang' is not described in schema (0% coverage). Description explains its effect with an example ('lang=fr returns locale equivalent'), adding necessary meaning.

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

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

Clearly states it returns a daily featured quote from English Wikiquote with optional language override. Not explicitly differentiating from sibling 'quotes' but the 'daily featured' and locale behavior provide distinction.

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?

Implies usage for fetching a daily quote in a specific locale, but lacks when-not-to-use or comparison to sibling 'quotes'. No alternative suggestions.

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, covering the safety profile. The description adds the note that quotes are 'sourced', but no additional behavioral traits 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?

The description is a single front-loaded sentence with no wasted words, effectively communicating the core function.

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

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

Given the presence of an output schema and annotations, the description is adequate but lacks context about the source (e.g., Wikipedia) and how to use the parameters effectively. Not fully complete for a tool with three parameters.

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 only 33% (only 'limit' has a description). The description does not explain the 'lang' or 'title' parameters, leaving their semantics unclear. With low coverage, the description should compensate but fails to do so.

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 'Extract' and the resource 'sourced quotation items from a page', which is specific and distinguishes this tool from the sibling 'quote_of_the_day' that likely returns a single quote.

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 no guidance on when to use this tool versus alternatives like 'quote_of_the_day' or other research tools. No explicit context for usage.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds value by explaining scoping to identifier and listing behavior (omit key). 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 clear, front-loaded sentences with no wasted words. Each sentence serves a purpose: action, context, scope, pairing.

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

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

Given the simple parameters and good annotations, the description covers behavior and context well. Could mention error handling for missing keys, but not essential.

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

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

Schema coverage is 100% with description for the key parameter. Description reinforces and elaborates on listing behavior and provides example use cases, adding value beyond the schema.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all keys. It uses specific verbs and distinguishes from sibling tools like remember and forget.

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

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

Provides clear guidance on when to use (to look up stored context without re-deriving) and mentions pairing with remember and forget. While it doesn't explicitly state when not to use, the 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?

The description contradicts annotations: annotations declare readOnlyHint=true, but the description states that setting mark_read:true flags events as read, which modifies state. This is a major inconsistency. Additionally, no other behavioral traits beyond what annotations provide are disclosed.

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

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

The description is four sentences, front-loaded with the core purpose, followed by return field details, filtering/mark_read behavior, and a note about polling. Every sentence adds value without redundancy.

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

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

Without an output schema, the description adequately explains return fields (source, citation_uri, payload) and key behaviors (filters, mark_read). However, it does not mention the limit parameter's effect, though the schema covers it. The contradiction with annotations reduces completeness.

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

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

Schema coverage is 100% (baseline 3). The description adds value by explaining the effect of mark_read (flags events as read), mentioning the 'pipeworx://' format for citation_uri, and clarifying that type and since are filters. This goes beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns recent alerts, and specifies available fields (source, citation_uri, raw event payload). It distinguishes from siblings like list_subscriptions by focusing on the alert feed rather than subscription management.

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 that polling works fine and points to an alternative endpoint (alerts.json) for scripts and dashboards. It also explains when to use mark_read. However, it does not explicitly state when not to use this tool or compare it to related tools like recent_changes.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: parallel fan-out to multiple sources, fallback logic, output structure (changes[] grouped by source, total_changes, citation URIs), and soft-fail for USPTO. 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 detailed but efficient, front-loading examples and purpose. Every sentence contributes meaningful information. Slightly verbose in parts (e.g., repeating fallback details) but still concise overall.

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 explains the return structure (changes[] grouped by source, total_changes, citation URIs). It covers input, behavior, output, fallbacks, and sibling distinction comprehensively. 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 has 100% description coverage for 3 parameters. The description adds value: for 'since', it explains accepted formats and gives monitoring recommendation; for 'type', it notes only 'company' supported; for 'value', it clarifies ticker or CIK. This goes beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It specifies the verb (provide change feed), resource (company), and scope (time window). It explicitly distinguishes from sibling tool entity_profile, stating when to use which.

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

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

The description provides explicit usage guidance: lists example queries ('What's new with X', 'latest on Y'), explains input formats (ISO date or relative shorthand), recommends '30d' or '1m' for typical monitoring, and directs users to entity_profile for static profiles. It also details fallback behavior for GDELT→GNews and USPTO soft-fail.

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

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

Annotations indicate idempotent, non-read-only, non-destructive. Description adds critical behavioral context: storage scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) sessions. 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?

Three sentences, front-loaded with purpose, then usage, then storage details. Every sentence adds value with no redundancy. Highly efficient.

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

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

Given the simple tool (2 params, no output schema) and comprehensive annotations, the description fully covers all necessary context: what to store, when, how storage works, 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?

Schema coverage is 100% with descriptions for both key and value. Description adds value beyond schema by providing concrete example keys (e.g., 'subject_property', 'target_ticker') and explaining the purpose of storing any text, which helps the agent understand parameter usage. Baseline 3 is elevated because description enriches parameter 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?

The description clearly states the tool saves data for reuse across conversations or sessions, and explicitly distinguishes it from sibling tools recall and forget. The verb 'save' with resource 'data' and scope 'across conversations or sessions' is specific and unambiguous.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward'. Also mentions when not to use by suggesting alternatives: 'Pair with recall to retrieve later, forget to delete.' This covers both usage context and exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses meaningful behavioral traits: graceful degradation of LEI/FIGI enrichment, internal cascading lookups, explicit labeling of source origins, and that unresolved identifiers are stated under 'unresolved' rather than omitted. This significantly adds 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 longer than average but stays dense with relevant details: examples, supported types, enrichment behavior, and fallback guarantees. It is front-loaded with query examples, and while not as terse as the 2-sentence archetype, every sentence adds value for a fairly complex tool.

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

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

With no output schema, the description carries the burden of explaining what the tool returns. It covers both entity types, identifier sources, unresolved handling, and failure modes. For a tool with two entity types and multiple lookup endpoints, this is remarkably complete.

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

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

Schema coverage is 100% with both type and value having detailed descriptions, including examples. The description largely repeats this information (e.g., ticker/CIK/name, brand/generic examples). It adds no additional parameter-level nuance beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's core function: resolving user-spoken names to canonical identifiers. It provides multiple example queries and explicitly differentiates itself from siblings by noting it supplies IDs that 'other tools require as input,' making it distinct from near-neighbors like entity_profile and compare_entities.

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

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

The description gives a strong usage directive: 'Use FIRST whenever you have a name but need an ID.' It also notes it replaces 2-3 manual lookups. However, it does not explicitly name alternatives or state when not to use it, so while the guidance is clear, it lacks explicit exclusionary context.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score/confidence/signal density per entity. No contradictions.

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

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

Four sentences with front-loaded purpose. Each sentence adds unique value: purpose, method, use case, output. No redundant or extraneous content.

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

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

No output schema, but description lists return fields (score, confidence, signal density) and explains the process. Could mention the entity count constraint (2-8) explicitly, but overall complete for the given 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 description coverage is 100%, so baseline is 3. Description does not add new parameter information beyond the schema; it mentions the 'entities' parameter contextually but does not elaborate on optional params like models, _apiKey, or 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?

Description clearly states the verb 'compare' and resource 'AI visibility across multiple entities'. It distinguishes itself from sibling ai_visibility_check by focusing on side-by-side comparison of multiple entities, and gives a concrete use case example.

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 context for use in competitive AI-marketing audits with an example question. Implies it is intended for multi-entity comparison versus single-entity check (ai_visibility_check), though does not explicitly state when not to use.

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

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

Describes the fan-out across multiple sources, return structure (summary block, per-advisory detail, links, alternative versions), and graceful degradation when sources fail. This adds substantial behavioral context beyond annotations, which only indicate readOnly, openWorld, idempotent, and non-destructive 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 well-structured, front-loading the main purpose and then detailing sources, return values, and edge cases. While slightly verbose, every sentence adds value, and the bullet-like listing aids readability.

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

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

Covers return structure in detail (summary block, per-advisory detail, links, alternative versions), ecosystem limitations (NPM only in v1), and partial failure behavior with sources_failed. No output schema exists, so description fully compensates.

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 extra context for both parameters: notes scoped packages accepted for 'package', and default behavior for 'version' (latest). This enhances understanding beyond the schema descriptions.

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

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

The description clearly states it's a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size metrics. It uses a specific verb (scan) and resource (dependency), and distinguishes itself from siblings by explicitly limiting to NPM ecosystem.

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

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

Provides explicit when-to-use criteria ('is X safe / popular / small' or 'what does adding lodash cost me'), notes NPM-only scope in v1, and advises on partial failures and timing (bundlephobia first measurement delay). This gives clear context for selection and expectations.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the agent knows it is safe. The description adds the specific scope (Wikiquote, title+fulltext) but does not elaborate on behavior like pagination, response format, or any constraints. It is adequate but minimal.

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 conveys the core functionality without fluff. It is front-loaded and efficient. However, it could benefit from additional context without becoming verbose.

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?

While the output schema exists and annotations provide safety, the description fails to explain parameter usage or when to employ this tool. The contextual completeness is low, as the agent remains underinformed about how to construct queries or how results are scoped.

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 only 33% schema description coverage, the description should clarify the missing parameter semantics for 'query' and 'lang'. It does not: the tool description only states it searches, without explaining what 'query' expects or what 'lang' does. This leaves the agent without necessary parameter guidance.

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

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

The description clearly identifies the tool as performing searches on Wikiquote, covering both titles and fulltext. However, it does not explicitly differentiate from sibling tools like 'search_within' or 'quotes', which might have overlapping functionality. The purpose is well understood but not contrasted.

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 no guidance on when to use this tool versus its siblings such as 'search_within' or 'quotes'. It lacks explicit context or exclusion criteria, leaving the agent to guess the appropriate use case.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds valuable context: truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping), cosine similarity, and offsets. No contradiction with annotations.

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

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

Three sentences: first states core purpose, second provides usage context and alternatives, third gives technical details. No filler. Every sentence is essential and informative.

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

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

Even without output schema, description explains return format (passages with offsets and similarity scores). Covers limitations (200K char cap, truncated flag). For a tool with moderate complexity, this is complete and sufficient.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with natural-language query examples and clarifies the output includes offsets and similarity scores. Goes beyond the schema by explaining the embedding approach.

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. Uses specific verb ('search within'), identifies the resource ('a fetched record'), and provides concrete examples (SEC 10-K, article). Distinguishes from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Mentions alternative sibling (ask_pipeworx_grounded) and gives a pairing strategy. Provides clear context for decision-making.

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 include readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds context about authentication requirements, the creation of persistent subscriptions, details on delivery channel behavior (always-on feed, optional email/sms/webhook with limits like SMS 10/day and webhook auto-disable after 10 consecutive failures), and the return of a new subscription ID. It does not contradict any annotations.

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

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

The description is relatively long but well-structured: it front-loads the core purpose, then details types and delivery channels in separate sections. Every sentence serves a purpose (examples, requirements, constraints). A slight trim could improve conciseness, but overall it is appropriately sized and organized.

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

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

Given 3 parameters with nested objects and no output schema, the description is highly complete: it covers parameter details comprehensively, specifies the return value (new subscription ID), explains side effects (persistent subscription), and outlines limitations (auth requirements, SMS cap, webhook auto-disable). No obvious gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema: for 'type', it explains each enum value with real-world examples (e.g., 'sec_8k' items codes); for 'params', it provides detailed JSON examples for each type; for 'delivery', it explains verification steps, limits, and webhook signing details. This greatly aids correct parameter construction.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It specifies the verb 'create' and the resource 'subscription', and distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description provides explicit guidance: requires a Pipeworx OAuth account (anonymous/BYO cannot persist), lists supported types with examples, explains delivery channels, and mentions limitations like SMS cap and webhook auto-disable. However, it does not explicitly state when not to use this tool (e.g., for viewing alerts, use recent_alerts).

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds that it returns questions with tool+argument shape from a live catalog, and how to use the topic parameter. No contradictions.

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

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

The description is somewhat long but front-loaded with the core purpose. Every sentence adds value, listing categories and usage variants. Could be more concise but is well-structured.

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

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

Given no output schema, the description fully explains return values (category-bucketed example questions with tool+argument shapes). Parameter coverage is complete. It covers all needed context for an onboarding tool.

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

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

Schema coverage is 100% and the description adds meaning beyond the schema: it explains that omitting topic gives full spread, while passing a topic focuses the output, with examples. This enhances understanding.

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

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

The description clearly states that the tool returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call with no arguments or a topic to focus. It implies when to use and provides context for alternatives.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. However, the description adds no additional behavioral context, such as what 'summary' entails or any side effects. With annotations covering the basics, a 2 reflects the lack of value added.

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 only two words, which is underspecified rather than efficiently concise. It fails to convey essential information and does not earn 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?

Given the presence of an output schema, the description should still explain the tool's behavior. It does not mention return values, scope, or anything beyond 'Page summary,' making it inadequate for an agent to understand what the tool does.

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 0%, meaning no parameter descriptions exist in the schema. The description does not explain the 'title' (required) or 'lang' parameters, leaving their purpose ambiguous.

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 'Page summary.' is vague and does not specify what the tool does beyond a generic term. It fails to distinguish from sibling tools like 'entity_profile' or 'deep_research', which likely also provide summaries in some form.

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

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

No guidance is provided on when to use this tool versus alternatives. There are many sibling tools, and the description offers no context 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?

The description adds critical behavioral context beyond annotations: ownership enforcement and deactivation (not deletion). Annotations indicate non-destructive and idempotent, which align 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?

Two sentences, front-loaded with the core purpose, then constraints. Every sentence adds value with 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?

Given one parameter, no output schema, and clear annotations, the description fully covers behavior, constraints, and side effects. References 'recent_alerts' for historical context.

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

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

The schema already fully describes the single parameter 'id' with 100% coverage. The description does not add additional semantic value 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 verb ('Cancel') and resource ('subscription'), and distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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 ownership enforcement (you can only cancel your own) and the deactivation behavior (not deleted, historical events stay). This gives context for when to use this tool, though it doesn't explicitly state when not to use or compare to all 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?

Goes well beyond the annotations: it discloses the routing logic, the return format (verdict types, citation, reasoning), and critically distinguishes 'could_not_verify' (internal failure, not evidence) from 'unsupported' (no source). Adds context about the verification_error structure and warns callers how to interpret results, which is vital for safe usage.

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

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

The description is long but densely packed with valuable information. It uses a clear structure: examples, purpose, routing logic, return values, and important caveats. While the opening list of paraphrases could be condensed, every subsequent sentence contributes unique meaning, making the length acceptable for a complex tool.

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 the return value (verdict enum, evidence, citation, reasoning), the failure semantics, and the routing. It also covers the tool's efficiency benefit. Given the tool's complexity, this description is exceptionally complete and leaves little 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?

The input schema already provides 100% coverage for both parameters, including a detailed explanation of tolerance_pct. The description itself doesn't add parameter-specific details except implicitly through the pipeline description. Since schema does the heavy lifting, a 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 gives a specific verb+resource: verifies natural-language claims against authoritative sources. It lists example phrasings and returns a verdict, clearly distinguishing it from generic search or ask tools. It also explains the composite nature (replaces 4–6 sequential calls), which clarifies its role among 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?

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also distinguishes between company-financial claims (SEC EDGAR path) and other claims (grounded pipeline). However, it does not name specific alternative tools to avoid, relying on context, so it misses some explicit exclusion guidance.

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