Nihr

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that the default model is free (Workers AI) and that Anthropic requires a BYO key with direct billing, plus return structure. No contradictions.

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

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

The description is a single paragraph with no wasted words. It front-loads the main action and key details, earning every sentence.

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

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

Despite no output schema, the description details the per-model return fields {score, confidence, signals, raw_response} and a combined view. It covers usage scenarios, parameters, and cost implications—complete for a probe tool.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context: default model, how _apiKey works, and purpose of context parameter, going beyond the schema.

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

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

The description clearly states the tool probes LLMs for brand visibility and scores it 0-100. It specifies the verb 'probe', resource 'LLMs', and output 'score visibility', distinguishing it from sibling 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 use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use it or compare to siblings, but the use cases are 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, idempotentHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: routing across thousands of sources, stable citation URIs, one fast call, and works on every tier. No contradictions with annotations.

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

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

The description is long but densely informative; every major block earns its place: preference directive, scope, examples, escalation guidance. Minor redundancy exists (e.g., 'even if web search could also answer it' and repeated mention of news), but overall it remains well-organized and front-loaded with the most important guidance.

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

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

For a tool with no output schema, the description sufficiently explains return shape ('structured answer with stable citation URIs'), domain coverage, trigger phrases, examples, and escalation paths to siblings. It leaves no major contextual gap for an agent deciding when and 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?

Schema description coverage is 100%, with the question parameter already documenting aliases like query, q, prompt, text, input. The description's examples ('current US unemployment rate', 'Apple's latest 10-K') illustrate content types but don't add parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description uses a specific verb+resource structure: 'Routes the question to the right one of 5,566 tools across 1462 verified sources' and 'returns the structured answer with stable pipeworx:// citation URIs.' It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its role 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 explicitly says 'PREFER OVER WEB SEARCH,' 'Use whenever the user asks...', and 'START HERE for most questions.' It also provides clear alternatives with 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.'

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

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

The annotations (readOnlyHint=true, destructiveHint=false) mark it as safe, and the description adds valuable context: the candidate routing system, the fact that it currently matches the stable version exactly, and the retirement date of the last candidate. The explicit 'Falls back to nothing' disclaims any safety net, giving a complete picture of the behavioral contract.

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 information-dense sentences, each earning its place: version status, candidate mechanism, usage directive, and the critical 'this IS a fully working router' warning. Slightly more verbose than strictly necessary (the candidate-retirement detail could be considered surplus), but the density to value ratio is high.

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 relatively simple invoke-with-a-question tool, the description is complete: it explains the current state (matches stable), the variability over time (candidate under test), and the implications for the caller (results are compared). The only gap is that it doesn't describe the response shape beyond 'same response shape' as the sibling—but with no output schema and a straightforward invocation contract, this is a minor omission.

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

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

Schema coverage is 100%, so the description doesn't need to add parameter details. The only added context—'same arguments, same response shape'—confirms schema stability but adds nothing beyond what the schema and the alias list already communicate. 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 identifies the resource ('universal router... 5,566 tools') and differentiates the beta from the stable sibling by noting it's the experimental edge. However, it never defines what the router actually does, assuming prior knowledge of ask_pipeworx's core function.

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

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

Explicitly names the stable alternative, gives a clear condition for when to use this version ('when you want the newest routing'), and explains what happens to the results (compared against stable to decide merges). Explicit when/why guidance is exactly what the rubric asks for.

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, but the description goes far beyond by detailing the exact return structure ({answer, evidence, confidence, source, fetched_at}), the refusal reasons, and the explicit 'using ONLY what the tool result contains' behavior. It also discloses the extra LLM call cost, which is not in annotations.

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

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

The description is dense but every sentence earns its place: it defines the mode, outlines the process, specifies the return format, lists refusal reasons, gives usage guidance, and notes the cost trade-off. It is front-loaded with the most critical information and maintains high information density without redundancy.

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

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

Given the tool's complexity (routing across thousands of sources, refusal scenarios, evidence extraction) and lack of an output schema, the description is remarkably complete. It covers the return structure, refusal semantics, usage context, and cost implications, making it self-sufficient for an agent to invoke the tool correctly.

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

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

The input schema already provides 100% coverage, documenting the 'question' parameter and five aliases with descriptions. The description adds no additional parameter-level meaning beyond the general context of what the question is used for. Since the schema fully handles parameter semantics, this dimension meets the baseline of 3.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode' and explains its two-step process (routing + extraction-only answer generation), which distinctly separates it from sibling tools like ask_pipeworx. The specific phrase 'EXTRACTS the answer using ONLY what the tool result contains' leaves no ambiguity about the tool's core function.

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

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

The description explicitly states when to use this tool: 'Use whenever an answer will be quoted, cited, or acted on...' and when not to: 'prefer ask_pipeworx for casual lookups.' It also names the direct alternative (ask_pipeworx) and explains the cost trade-off ('Costs one extra LLM call').

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?

Extremely detailed behavioral description: explains market resolution, classification, parallel fan-out, response shape with evidence packet and model comparison, resolver contract, parent event extraction, news fallback fields, safety mechanisms (low-confidence closure, closed market, wide spread handling), cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent and enriched by description. 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 lengthy but well-structured: starts with a concise summary, then partitions into classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, news fields, safety, and cancellation rules. Every section adds necessary detail for a complex tool. However, some sections are very verbose (e.g., cancellation rule parsing details). Could be slightly more concise, but structure earns a 4.

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

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

Given the tool's complexity (multiple data sources, edge cases, response shapes), the description is extremely complete. It covers all scenarios: low-confidence matches, closed markets, wide spreads, cancellation rules, parent events, news fallbacks. No output schema, so the description thoroughly explains return structure (result.market, result.analysis, result.evidence). No missing information for effective use.

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

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

Schema coverage is 100% (all 3 parameters described). Description adds value: for 'market', it clarifies acceptable formats (slug, URL, question text). For 'depth', it explains the difference ('quick = 2-3 evidence sources, thorough = full fan-out'). For 'include_raw', it describes when to use true (recomputation, citation, post-processing) and the size implications. Provides examples in schema and description.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet via Pipeworx data) and the action (research). Distinguishes from sibling tools by focusing on in-depth data retrieval and analysis, not just edges or arbitrage. Provides concrete usage examples.

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

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

Explicitly states when to use: 'Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'.' Does not explicitly state when not to use or mention alternatives, but the context from sibling tool names and the detailed fan-out examples imply this is for comprehensive research. Clear context but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral details: it pulls latest 10-K revenue/net income/cash/debt for companies (with fiscal year handling), FAERS adverse-event counts and FDA approval counts for drugs, and sorts results by primary metric. No contradictions with annotations.

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

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

The description is a single paragraph but packs significant information with minimal redundancy. It uses trigger phrases and dashes to structure ideas. Could be slightly more structured (e.g., bullet points) for easier parsing, but overall it is concise and front-loads the core purpose.

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

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

Given the simple schema (2 parameters, no output schema) and rich annotations, the description covers all necessary context: what data is returned per type, how results are sorted, and the efficiency gain over sequential lookups. It is complete for an AI agent to understand when and how to use the tool.

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

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

Schema coverage is 100%, but the description enriches both parameters: it explains the enum values for 'type' (what each pulls), clarifies that 'values' should be tickers/CIKs for company and drug names for drug, and reinforces the min/max constraints. This goes beyond the schema's descriptions.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resource (2–5 companies or drugs) and the action (comparison of financial or trial data). It distinguishes itself from sibling tools like entity_profile by explicitly stating it replaces sequential single-entity lookups and by listing trigger phrases.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over sequential single-pack lookups when comparing entities') and provides clear context for each type (company vs drug), including the data sources and metrics pulled. It also specifies the range of entities (2–5) and gives example inputs.

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 account/paid requirements, time expectations, decomposition and parallel routing, findings packet structure with gaps[] and contradictions[], citation_uri resolvability, and semantic excerpting. Annotations already declare readOnly/idempotent/openWorld, and description does not contradict them.

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

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

Front-loaded with account requirement, then dense but every clause adds functional detail (gaps, citations, hops, timing, non-open-web). Slightly verbose but justified for a complex tool; could be restructured but 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?

No output schema exists, so description carries return-value disclosure: verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop, citation_uri. Complexity is high and all major facets (auth, timing, depth, limits, alternatives) are addressed.

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

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

Schema covers both parameters (question and depth) with descriptions; description adds meaning by explaining depth levels (quick=3 facets, standard=3 with gap-recovery + contradictions, thorough=6 with iterative hop) and giving example question forms, enriching 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?

States 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' in one call, with a specific verb (research) and resource (structured data sources). Explicitly contrasts with open-web search and with ask_pipeworx for single lookups/current news, so it clearly distinguishes 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?

Explicitly says when to use: 'Best for broad/multi-part questions over structured data', and when not: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and if not signed in use ask_pipeworx. Names alternative tools directly.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that results include full schemas with examples, are ready to call, and no second lookup is needed—useful behavioral context beyond annotations. Slight missed opportunity to mention result ranking or pagination.

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 but not excessively long. It front-loads the purpose, enumerates example domains, and ends with usage guidance. The domain list could be slightly trimmed but is helpful for illustration.

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 fully explains the return value: tool names, descriptions, full schemas with examples, ready to call. It also addresses the pain point of 'no second schema lookup,' making it complete for an agent.

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

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

Schema coverage is 100% with detailed descriptions for all 6 parameters. The description adds little beyond restating that 'query' accepts natural language. Baseline 3 is appropriate as the schema does the heavy lifting.

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 tools by describing data or tasks, listing many domains. It distinguishes itself from siblings by advising 'Call this FIRST' when exploring available tools, making its role as a meta-tool explicit.

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

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

Provides explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST... when you want to see the option set (not just one answer).' This effectively tells the agent when to use it versus other tools.

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

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

Annotations already mark as read-only and idempotent. Description adds behavioral details: fans out across multiple sources, returns specific fields, notes patent API sunset with soft-fail, and mentions parallel execution. No contradictions.

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

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

Description is substantial but every sentence is informative. Front-loaded with examples and usage guidance. Minor improvements could make it more concise without losing content.

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

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

Without output schema, the description fully details return fields (cik, filings, fundamentals, patents, news, LEI) and limitations (patent sunset, name restriction). Complete enough for an 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%. Description adds examples and clarifies that names are not supported, reinforcing the schema. Slightly redundant but helpful.

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

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

The description opens with specific query examples and clearly states 'full cross-source profile of a US public company in ONE parallel call.' It distinguishes itself from sibling tools like 'resolve_entity' and 'compare_entities' by indicating it provides a holistic view.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using 'resolve_entity' first if only have a name. Provides clear context on when and when not to use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context that this is about 'sensitive data the agent saved earlier' and clarifies the action as deletion, which aligns with destructiveHint. It does not contradict annotations. The description enriches behavioral context by explaining the motivation (clearing stale context or sensitive data), which goes beyond what annotations alone provide.

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

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

Two concise sentences front-load the purpose and then provide usage guidelines. Every word adds value; there is no redundancy or filler. Extremely well-structured for an AI agent to parse quickly.

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 required parameter, no output schema), the description covers all necessary aspects: what it does, when to use it, and how it relates to siblings. No additional context is needed for correct invocation.

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

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

Input schema coverage is 100%, with the 'key' parameter fully described ('Memory key to delete'). The description adds no additional information about the parameter beyond what is in the schema. Baseline is 3, and no extra value is provided.

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

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

The description clearly states the action ('Delete a previously stored memory by key'). The verb 'Delete' is specific and directly indicates the resource being acted upon ('memory'). It also implicitly distinguishes itself from sibling tools like 'remember' and 'recall' by mentioning them in a pairing context.

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

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

The description provides explicit usage scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', offering guidance on complementary tools. However, it does not explicitly exclude situations where this tool should not be used or suggest direct alternatives beyond the paired tools, which would make it a 5.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds that it fetches the page, extracts title/description/key links, and returns markdown text. This aligns with annotations and provides behavioral context, though it could mention that no modifications are made to the site.

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

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

The description is concise: two sentences plus a brief list of use cases. It is front-loaded with the core action and every part adds value, with no redundant or superfluous 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?

Given the tool's simplicity (2 parameters, no output schema), the description adequately covers functionality, output format, and use cases. It does not cover error handling or limitations (e.g., invalid URLs), but for a straightforward tool this 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 description coverage is 100%, so the schema already documents both parameters well. The description reinforces the meaning of 'url' (site to summarize) and 'max_links' (controls number of link entries) but does not add significant new information beyond the schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action (fetch, extract, emit) and the output format. It distinguishes itself from sibling tools like 'ai_visibility_check' or 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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 use cases: getting a client's site indexed, drafting llms.txt for own project, or auditing competitor AI visibility. It provides clear context but does not mention when not to use this tool or prerequisites like URL accessibility.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return field list and confirms active subscriptions, providing useful behavioral 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?

Two sentences: first covers purpose and output, second gives usage guidance. No extraneous information, every sentence earns its place.

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

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

For a simple list tool with rich annotations and one optional parameter, the description sufficiently covers purpose, output, and usage. No gaps for correct agent invocation.

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

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

Schema coverage is 100% with one parameter fully described. Description does not mention the parameter, but schema carries the burden. Baseline score of 3 is appropriate.

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

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

Description clearly states verb 'list', resource 'subscriptions', and scope 'caller's active'. It also lists returned fields, making purpose unambiguous. Siblings include subscribe/unsubscribe, so it effectively distinguishes.

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 to use for reviewing monitoring before adding more or to find an id to cancel. Provides clear usage context, though it does not explicitly mention when not to use.

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

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

The description aligns with all annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) and adds behavioral context: it returns matching award holders with their ORCID, role, and project IDs, and mentions the data size (12,644 records). No contradictions.

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

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

The description is two sentences, front-loaded with purpose and method, then details returns and examples. Every sentence adds value with no fluff.

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

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

Given 6 parameters (none required), no output schema, and simple query functionality, the description is complete. It explains input methods, return fields, and example queries, enabling the agent to understand how to invoke the tool and interpret results.

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

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

Schema coverage is 100%, so the schema already documents all 6 parameters. The description adds minor nuance for the 'name' parameter (titles may be included or omitted) and provides examples, but overall adds limited value beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'find', the resource 'researchers named on UK NIHR awards', and the methods 'by personal name or ORCID identifier'. It specifies what is returned (ORCID, role, project IDs) and gives concrete query examples, distinguishing it from siblings like 'nihr_get_award' and 'nihr_search_awards'.

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

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

The description includes explicit use cases: 'which NIHR grants does Professor X hold', 'who is the chief investigator', and ORCID-to-grant lookups. It also mentions pivoting to 'nihr_get_award' for grant detail. However, it does not explicitly state when NOT to use this tool or what alternatives exist among siblings, so slightly lower.

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. The description adds that totals cover all matches regardless of pagination, explains substring matching, and lists returned data types. This adds value beyond annotations 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?

Three concise sentences: first states core function, second lists outputs, third gives example queries. No fluff, front-loaded with the most important information.

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

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

Given 6 parameters, 1 required, no output schema, the description adequately covers key aspects: substring matching, pagination behavior, aggregate totals, time filtering (via start_from). It could more precisely detail output structure, but the provided examples and parameter descriptions fill 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%, so baseline is 3. The description adds a usage example (limit=10, organisation='Imperial College') and clarifies that the limit only affects listed awards, not totals. This provides extra practical context 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 totals up NIHR funding for an institution, listing specific return values (number of awards, sum, breakdown, individual awards) and giving concrete example queries. It distinguishes from sibling tools like nihr_awards_by_programme and nihr_get_award by focusing on organisational aggregation.

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

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

The description implies use for organisational funding queries and provides example questions, but does not explicitly state when to use this tool versus alternatives like nihr_search_awards or nihr_awards_by_programme. The sibling tool list provides context but the description lacks explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds behavioral context by explaining the discovery pattern (no arguments lists all programmes) and that it aggregates data, which goes beyond the annotations.

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

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

The description is a single coherent paragraph that front-loads the core function. It is concise and every sentence adds value, though it could be slightly more structured for 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?

Given 6 optional parameters and no output schema, the description adequately explains the tool's purpose, usage pattern, and output fields (counts, total value, mean size, date range). It fully covers what an agent needs to know.

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 fully described in the input schema (100% coverage). The description does not add additional meaning to individual parameters beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it breaks down UK NIHR funding by programme or funding stream, providing award counts, total value, mean size, and date range. It gives concrete example questions and distinguishes from sibling tools like nihr_awards_by_organisation.

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 calling with no arguments lists every programme to discover valid names before filtering. It provides example questions but does not explicitly state when not to use or list alternatives, though the sibling context is available.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description supplements this by detailing exactly what data is returned (abstracts, award value, coding, etc.), providing complete transparency about the tool's behavior 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 a single, dense paragraph that front-loads the primary action and then enumerates return fields. Every sentence adds value, with no filler. It is appropriately sized for the complexity of the 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 a single parameter, full schema coverage, comprehensive annotations, and no output schema, the description covers everything needed for agentic use: what the tool does, what input is expected, and what output is returned. No gaps remain.

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

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

Schema coverage is 100%, so the description's contribution over the schema is modest but meaningful. It explains the two forms of the project id (modern NIHR208893 and older slash form) and notes that slashes are handled, adding practical context 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 uses specific verbs ('Retrieve') and a clear resource ('one UK NIHR award in full by its project id'). It also distinguishes the tool from siblings by specifying the exact identifier formats and the depth of information returned (abstracts, awards details, etc.). This makes the purpose highly 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 states when to use the tool: 'Use when an agent has an NIHR project reference and needs the detail behind it.' While it does not mention when not to use or name alternatives, the context is clear given the sibling tools like nihr_search_awards. It provides sufficient guidance for typical 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 indicate read-only, idempotent, non-destructive. Description adds that it searches titles and abstracts, returns specific fields, supports pagination and sorting. No contradiction, but could mention if data is real-time.

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 focused paragraph that front-loads the core purpose and then lists features. Every sentence adds value; no fluff.

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

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

Given 13 parameters and no output schema, the description covers all major aspects: search, filtering, sorting, pagination, and returned fields. It is adequate for an agent to invoke correctly.

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

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

With 100% schema coverage, baseline is 3. Description adds value by clarifying matching behavior ('unless title_only is set'), default sorting, and providing examples for min_amount. It also explains how to use programme parameter with a sibling call.

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 searches UK NIHR health research grants by keyword over award titles and abstracts, and lists the returned fields. It distinguishes from siblings like nihr_get_award and nihr_awards_by_programme.

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

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

Provides explicit examples of questions it answers ('which NIHR grants fund diabetes research') and cross-references sibling tool for programme names. Parameter descriptions include usage guidance like 'Restrict the keyword match to the award title for a tighter...' and 'default amount_desc'.

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

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

The annotations only provide false hints, but the description richly discloses behavior: anonymous filing returns a claim_token for later status checks, rate limiting to 5 per identifier per day, that it is free and doesn't count against quota, and that maintainers read digests daily. This fully compensates for the sparse annotations and adds concrete expectations.

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

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

The description is long but every sentence carries distinct value: purpose, types, exclusions, token flow, rate limit, roadmap impact. The first sentence front-loads the core purpose and sections are logically ordered. Minor redundancy with the schema's enum descriptions (e.g., praising when something worked well) slightly blunts conciseness, but it remains 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?

The tool has dual modes (submit vs read status), intricate ownership rules, and no output schema. The description covers all essential context: when to use, what to write, how to identify Pipeworx tools, claim_token flow, rate limiting, and business impact. It is virtually self-contained for an agent to invoke correctly.

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

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

Although the schema already documents all parameters at 100% coverage, the description adds operational meaning: it shows the exact call form for claim_token (`pipeworx_feedback({claim_token:"pwfb_…"})`), states that no other arguments should be passed with it, and links the `type` enum values to concrete real-world triggers (e.g., 'feature/data_gap' for a tool that doesn't exist). This surpasses the schema alone.

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

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

The description opens with a clear verb+object ('Tell the Pipeworx team something is broken, missing, or needs to exist') and enumerates specific feedback types (bug, feature, data_gap, praise). It distinguishes itself from sibling research/investigation tools by framing feedback exclusively about Pipeworx's own tooling.

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 conditions (wrong data, missing tool, praise) and an explicit exclusion (do not report other MCP servers' tools; file with that server instead). It also offers a disambiguation rule: 'Not sure? Pipeworx tool names are the ones this connection lists.' This goes well beyond basic guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds valuable context: 'Self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h depending on window.'

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 well-structured sentences: output, use cases, caveats. No wasted words; front-loaded with key information.

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

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

For a single-parameter, no-output-schema tool with robust annotations, the description fully covers purpose, usage, behavior, and caching. Nothing missing.

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

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

Schema covers 100% with enum and description. Description adds semantic nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' beyond schema.

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

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

The title 'Pipeworx Trending' and description clearly state it returns top tools, packs, and call volume over recent windows. It distinguishes from siblings like 'discover_tools' by focusing on aggregate usage trends.

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

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

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case with demand). While it doesn't mention when not to use, sibling names provide 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 mark the tool as read-only, open-world, idempotent, and non-destructive. The description adds significant behavioral context: describes the response structure (opportunities[], partition_check), explains fill check logic (theoretical vs realizable edge), and warns against trading when realizable_edge_pp <= 0. No contradictions.

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

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

Description is somewhat lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loads main purpose and usage modes. Some details like 'skipped_low_similarity surfaces the rejected pair count' could be moved to parameter descriptions, but overall not wasteful. Scores 3 for moderate conciseness.

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

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

Given the tool has 2 optional parameters, no output schema, and high complexity, the description covers purpose, usage modes, behavioral nuances, and response structure comprehensively. Includes important constraints like Jaccard similarity threshold and placeholder filter. Adequate for an AI agent to correctly select and invoke the tool.

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

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

Schema has 100% coverage with descriptions for both event and topic. The description adds value beyond schema by explaining the semantic difference, giving example inputs, and describing behavioral differences between modes (e.g., cross-event catches date-axis patterns single-event misses). Schema already adequate, so baseline 3; description adds enough extra context to warrant 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?

Clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' Distinguishes from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by specifying unique methodology.

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 describes three usage modes: no args for trending_scan, event for single-event partition checks, topic for cross-event scanning. Provides specific guidance on when to use each, e.g., 'event (recommended for a specific market)' and explains cross-event mode catches patterns single-event misses. Also advises using polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations, including caching (1h KV-level), return fields (edge_pp_net, kelly fractions, liquidity, spread, volume, 24h-move warning), model families, and diagnostics. Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds rich context about internal calculations and filtering logic.

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 comprehensive but verbose, with complex sentences and detailed enumerations. While it is well-organized into sections (model families, knobs, response structure), it could be trimmed without losing essential information, scoring it as adequately structured but not optimally concise for 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?

Despite the absence of an output schema, the description explains the complete response structure (by_segment segments, fed_candidates/diagnostics) and the meaning of each returned field. The tool is complex with three segments and diagnostics, and the description covers all aspects needed for an agent to understand what to expect, making it fully complete.

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

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

Schema coverage is 100%, and the description adds significant meaning beyond the schema for each parameter. For example, it explains the context for slippage_pp ('Bump for very thin partitions; drop to 0 if you have a smarter fill model') and clarifies the interaction between min_kelly and min_partition_leg_kelly, providing actionable guidance that the schema alone does not offer.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It explicitly distinguishes its purpose as a discovery tool for "what should I bet on today" and breaks down three model segments, making the verb+resource specific and distinctive from siblings like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear guidance on when to use the tool (discovery without paging hundreds of markets) and explains tradeable-edge knobs for filtering. However, it does not explicitly mention when not to use it or directly contrast with sibling tools such as polymarket_edge_tracker for tracking specific edges, leaving some room for improvement in exclusionary guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant behavioral detail: response structure (tracked, expired, snapshot_dates), computation details (decay from daily closes, not intraday), and data availability conditions (snapshots written on cache-miss). 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 verbose but well-organized with clear sections for purpose, response structure, and limits. Every sentence provides useful information, though some streamlining could reduce length without losing value.

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

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

No output schema is provided, but the description fully explains the return format including fields for tracked, expired, and snapshot_dates along with their meanings. It also covers limits (60-day TTL, computation details). For a time-series telemetry tool, this is comprehensive.

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% (both parameters have descriptions). The description adds minimal extra meaning beyond re-stating defaults and clamping boundaries. Baseline 3 is appropriate as schema already does the heavy lifting.

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 providing edge persistence and decay telemetry from daily snapshots. It uses specific language like 'answers how long has this edge existed and is it shrinking?' and distinguishes from sibling tool 'polymarket_edges' by focusing on historical time-series rather than current edges.

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

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

The description explains when to use this tool—when needing to know edge longevity and decay trends—and contrasts fresh vs. old wide edges. It provides context on limits (60-day TTL) but does not explicitly state when not to use or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it explains that the tool simulates fills (walks the ladder, returns slippage, verdict) and warns about forced directional risk. No contradictions.

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

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

The description is well-organized into sections (single-market vs basket) and front-loads the core purpose. However, it is somewhat verbose (nearly 4 paragraphs with complex sentences). While detail is appropriate for a complex tool, slight tightening could improve conciseness.

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

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

Given the complexity (4 parameters, no output schema), the description is highly complete. It covers all modes, parameter interpretations, return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), warnings about thin books, and forced directional risk. 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 description coverage is 100%, but the description adds meaning beyond the schema. For example, it explains that in basket mode, size_usd is 'settlement notional — shares per leg, each paying $1 at resolution,' and that side defaults to 'auto from partition sum.' This clarifies parameter semantics significantly.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It is specific about the resource (Polymarket markets/events) and the action (check fill risk). Among sibling tools like polymarket_arbitrage, it carves a distinct role.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and warns that partial basket fills convert arb into an unhedged directional position. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent behavior, and the description adds deep transparency: it explains how spreads are computed only when bet shapes match, details compatibility warnings, temporal alignment, and skipped leg counters. No contradictions with annotations.

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

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

The description is well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. It is somewhat dense but every sentence adds value. Could be slightly more concise, but overall very effective.

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

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

Without an output schema, the description provides a good overview of the response format (leg-by-leg prices, top_spreads_pp, safety fields). It covers the essential behavioral details. A complete output schema would improve it, but given the absence, it is fairly comprehensive.

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

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

Schema coverage is 100%, and the description adds significant value: for 'topic', it lists all 10 shortcuts; for 'kalshi_event_ticker' and 'polymarket_event_slug', it provides examples and explains they override the mapped side. This goes well beyond the schema alone.

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

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

The description clearly states the tool's purpose: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the two modes (topic shortcuts and explicit tickers) and includes details on the response, making it distinct from sibling tools like polynarket_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 each mode and provides important caveats, such as the rarity of real spreads and the role of compatibility warnings. However, it does not explicitly contrast with alternatives like polynarket_arbitrage, though the purpose is distinct enough.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds scoping by identifier and the listing behavior when omitting key, providing useful 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?

Three sentences, front-loaded with core purpose, no fluff. Efficient structure.

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 purpose, usage, scope, relationship to siblings. Lacks description of return format, but tool is simple and for a single-parameter, read-only operation, it is nearly complete.

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

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

Schema description covers the parameter well (100% coverage). Description adds examples but no additional semantics beyond what schema already provides.

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

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

Clearly states the tool retrieves a value by key or lists all keys. Distinguishes from siblings (remember and forget) and gives concrete examples of stored items.

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 to use for looking up previously stored context without re-deriving. Pairs with remember and forget, providing a clear context, though no explicit when-not-to-use.

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

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

The description contradicts annotations: it describes a side effect (mark_read) while annotations declare readOnlyHint=true, implying no state changes. This is a serious inconsistency that undermines trust.

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

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

The description is two sentences, front-loaded with the main purpose, and includes necessary details without verbosity. It could be slightly more compact 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 and 5 optional parameters, the description covers return fields, filtering options, the mark_read side effect, polling suitability, and an alternative access method. It is comprehensive for a query 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 description adds context beyond the schema (e.g., 'ISO timestamp' for since, 'sec_8k' as type example, and the effect of mark_read on future calls). With 100% schema coverage, the description still adds value by clarifying behavior and providing examples.

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 pulls fired events from the subscription feed, specifying the resources returned (source, citation_uri, raw payload). It is specific about the tool's function and distinguishes it from siblings by focusing on alerts rather than changes or 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?

The description provides context on when to use this tool (e.g., polling is fine) and mentions an alternative endpoint for scripts. However, it does not explicitly guide the agent on when to use this tool over other siblings like 'recent_changes' or 'list_subscriptions', limiting its usefulness for selection.

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

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

Beyond the annotations indicating read-only and idempotent behavior, the description details the underlying data sources (SEC EDGAR, GDELT→GNews fallback, USPTO), notes that USPTO soft-fails until reactivated, and explains that the tool fans out in one parallel call. This provides a thorough understanding of the tool's 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 well-structured, starting with example queries, then explaining functionality, sources, parameter, return format, and alternative. It is efficient with no unnecessary words, though it is relatively long. Every sentence adds value, but it could be slightly more concise. Still, it is clear 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?

Given the tool has 3 required parameters, no output schema, and moderate complexity with multiple data sources and fallback logic, the description covers everything needed: input format, data sources, return structure (grouped changes, total count, citation URIs), and a clear alternative. It is complete and leaves no major 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?

All three parameters are described in the input schema with 100% coverage, so the baseline is 3. The description adds extra context by providing examples for the `since` parameter (e.g., '7d', '30d', '3m', '1y') and recommending '30d' or '1m' for monitoring, and clarifies that `value` accepts ticker or zero-padded CIK. This added usage guidance 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 provides a change feed for a company, listing multiple example queries such as 'What's new with X' and 'latest on Y'. It explicitly differentiates from the sibling tool entity_profile by recommending its use for static profiles.

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

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

The description provides specific when-to-use guidance with example queries and explicitly tells the agent to use entity_profile for static profile. It also gives parameter recommendations, like using '30d' or '1m' for typical monitoring of the `since` parameter.

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 significant context beyond annotations: key-value scoping by identifier, persistence for authenticated users, 24-hour retention for anonymous sessions. 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?

Three well-structured sentences with no redundancy. Front-loaded with core action, followed by usage context and behavioral notes.

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

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

Given the tool's simplicity (no output schema, 2 parameters), the description covers purpose, usage, behavior, and parameter examples 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?

Schema already describes both parameters clearly. Description adds concrete examples for key (e.g., 'subject_property', 'target_ticker') and value ('findings, addresses, preferences'), enhancing practical 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?

Description explicitly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools recall and forget by positioning them as complementary.

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?

Directly says 'Use when you discover something worth carrying forward' and advises pairing with recall and forget. Though it doesn't state when not to use, the context is clear and actionable.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable non-obvious behavior: graceful degradation when GLEIF or OpenFIGI is unavailable, explicit listing of unresolved identifiers, and internal cascading through multiple lookup endpoints. No contradiction.

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

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

The description is dense and well-structured but fairly long. However, every section earns its place: natural-language triggers, supported types, enrichment details, and fallback behavior. It is front-loaded with examples and avoids fluff.

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

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

Given the tool's complexity (two entity types, multiple data sources, enrichment fallbacks) and the absence of an output schema, the description is remarkably complete. It explains return contents, unresolved handling, and internal cascading, leaving little ambiguity for an agent.

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

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

Although the schema covers both parameters, the description adds substantial semantic depth: for 'company' it explains the cross-source identity spine, accepted input forms (ticker/CIK/ISIN/name), and LEI/FIGI enrichment; for 'drug' it details RxCUI/ingredient/brand output. This goes far 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 a specific verb 'resolve' and clearly states the tool's output: canonical/official identifiers needed by other tools. It distinguishes itself from sibling tools like entity_profile by framing itself as the name-to-ID lookup tool with concrete examples.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and provides supported types and example queries. It doesn't name alternative tools or state when not to use it, but the guidance is clear and contextually strong.

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

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

The description goes beyond annotations by explaining that the tool probes each entity with ai_visibility_check, ranks results by score, and returns a ranked list with score, confidence, and signal density. Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior, and the description adds valuable behavioral context without contradiction.

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

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

The description is concise (three sentences) and well-structured: first sentence states the action, second explains the process, third provides a use case and return value summary. No redundant information.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description covers essentials: process, return format, and use case. It could mention entity count limits or error handling, but overall it is sufficiently complete for a read-only, non-destructive tool with good 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?

With 100% schema description coverage, the baseline is 3. The description adds meaning by specifying that the first entity is treated as the 'subject' for narrative and that context disambiguates common names. It does not significantly elaborate on models or _apiKey, but the schema descriptions are already clear.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It explains the process of probing each entity with ai_visibility_check, ranking by score, and surfacing most/least recognized. This distinguishes it from siblings like ai_visibility_check (single probe) and compare_entities (general comparison).

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

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

The description provides a clear use case: 'competitive AI-marketing audits' with an illustrative question. It implies this tool is for comparing multiple entities, contrasting with the single-entity probe ai_visibility_check. However, it does not explicitly mention when to use or avoid alternatives like compare_entities, leaving some ambiguity.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds details on partial failures, bundlephobia latency (5-30s), and sources_failed behavior. No contradiction.

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

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

Long but efficient, every sentence adds value. Front-loaded with composite nature. Slightly verbose in middle but acceptable.

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

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

No output schema, but description details return block fields, per-advisory detail, links, alternatives. Complete for the tool's scope.

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

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

Schema covers both parameters fully (100% coverage). Description adds minor context (defaults to latest) but mostly repeats 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's a composite check for npm packages covering license, advisories, bundle size, etc. Distinct from sibling tools which are unrelated.

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 to use when agent asks about safety, popularity, or cost of adding an npm package. Also notes NPM-only and mentions deps.dev:version for other ecosystems.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals detailed behavioral traits: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output format including offsets and scores. No contradictions with annotations.

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

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

The description is concise at five sentences, front-loaded with the core purpose, and every sentence provides useful information without unnecessary words. It efficiently covers use case, behavior, and output.

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

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

Given no output schema, the description fully explains return values (top-N passages with offsets and scores), input constraints (200K cap), and behavior (truncation flag). It covers all necessary context 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?

With 100% schema description coverage, the baseline is 3. The description adds value by reinforcing the 'max ~200K chars' for text and providing query examples. This goes beyond the schema but does not substantially new information beyond reinforcing constraints.

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

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

The description clearly states it performs semantic search inside a fetched record, using verb 'search' and specific resource 'record'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and emphasizing internal search over external tools.

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

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

The description explicitly advises using this tool when 'the record is too big to cram into the prompt' and recommends pairing with another specific tool. However, it does not explicitly state when not to use it or provide alternative tools for contrast.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description aligns: it creates a subscription (write), is idempotent, and non-destructive. It also discloses account prerequisites, SMS caps (10/day), webhook auto-disable after 10 failures, and HMAC signing. 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?

Well-organized: core purpose, then types, then delivery channels. The webhook detail is lengthy but valuable. Every sentence adds meaningful information; could be slightly more concise without losing clarity.

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

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

For a complex tool with multiple subscription types, delivery channels, and validation requirements, the description covers everything needed: account prerequisites, supported types, parameter syntax, delivery options, failure behavior, and limitations (SMS cap, webhook auto-disable). Output schema is absent but subscription id is mentioned.

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 value: concrete examples for each type (e.g., sec_8k items codes, fred_series series_id), detailed param structures, and delivery constraints (SMS must match verified phone, webhook HMAC). Far exceeds 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 it creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation and specifying supported event types.

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

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

Provides when to use (subscribe to alerts), mentions account requirements (Pipeworx OAuth), and limitations (anonymous/BYO cannot persist). It gives type-specific examples and delivery options but does not explicitly contrast with sibling tools like recent_alerts or polymarket_edge_tracker for one-time queries.

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. The description adds that results are category-bucketed with tool+argument shapes from a live catalog, and explains the effect of 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 verbose, opening with several synonymous phrases. While well-structured and front-loaded, it could be more concise without losing clarity.

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

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

Given the single optional parameter and lack of output schema, the description adequately explains the tool's role, usage, and output. It covers purpose, usage guidelines, and expected results, making it sufficiently complete for correct invocation.

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

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

Schema coverage is 100% and the description for the topic parameter mirrors the schema exactly. No additional meaning is added beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states it is the onboarding entry point for an agent to learn what Pipeworx can do. It uses specific verbs and resources, distinguishing it from sibling tools by being the first action to take when unsure of capabilities.

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

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

It explicitly states to use this tool first when uncertain about Pipeworx's capabilities or to learn meta-tool usage. It provides calling conventions (no args or topic), but does not explicitly state when not to use it, 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?

The description discloses key behavioral details beyond annotations: the row is deactivated (not deleted) and historical events remain accessible via recent_alerts. 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?

Two concise sentences with no wasted words, front-loading the core purpose and ownership rule.

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 (one required param, no output schema), the description covers purpose, ownership, and behavioral outcome completely.

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

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

Schema coverage is 100% with a description for the 'id' parameter; the description adds no further semantic value beyond stating 'by id', which is already clear from the schema.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id', and distinguishes itself from siblings like 'subscribe' and 'list_subscriptions'.

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

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

It explicitly states ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for appropriate use, though it doesn't explicitly mention when not to use or alternatives.

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

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

The description goes well beyond annotations by detailing the internal routing (SEC EDGAR fast path vs. grounded pipeline), the full verdict set, citation format, and the crucial distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source exists). This is critical behavioral context that annotations do not 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 relatively long but well-structured, front-loading trigger phrases and then logically covering routing, returns, and error semantics. Every sentence adds substantive information, so while not ultra-concise, it earns 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?

The description is comprehensive for a tool with this complexity: it covers trigger phrases, routing logic, output format (verdicts, evidence, reasoning), error semantics, and parameter nuance. It also explains the efficiency benefit over sequential calls. No important operational aspect is left unexplained.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the semantics of tolerance_pct (overrides implied tolerance, useful for hallucination detection) and provides concrete examples for the claim parameter, enhancing parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'natural-language claim verification against authoritative sources' with explicit trigger phrases ('fact check', 'verify the claim that'). It distinguishes itself from siblings by its single-call replacement of a multi-step pipeline and its specific focus on claim verification.

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 context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also describes the routing behavior for company-financial vs. other claims. However, it does not name specific alternative tools or state when not to use, so not a perfect 5.

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