Peeringdb

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive, so the bar is lower. The description adds valuable behavioral context: the default free model, that using Anthropic requires a BYO key with direct payment to Anthropic, and the return structure (per-model score, confidence, signals, raw_response + combined view). This goes beyond the structured annotations and helps set expectations about cost and output.

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 total: the first states the core function and output, the second covers the default and optional API key with cost implications, and the third lists use cases. No filler, every sentence adds distinct value, and the most critical information is front-loaded.

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

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

Given strong annotations (readOnly, idempotent, openWorld, non-destructive), 100% schema coverage, and no output schema, the description supplies the needed return format (per-model fields + combined view) and practical context (cost, defaults, use cases). This is sufficient for an agent to select and invoke the tool correctly without ambiguity.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining the default model (Workers AI Llama-3.3-70b free), that models can be omitted to use only the default, and that _apiKey is required only when probing Anthropic. It also clarifies the 'entity' parameter scope (brand, product, person, topic) which aligns with the schema's examples, adding enough to warrant a 4.

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

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

The description opens with a specific action ('Probe one or more LLMs') and a clear resource ('what they know about a business / brand / product / topic'), then explains the scoring output (0-100 per model). This clearly distinguishes it from sibling tools like ask_pipeworx (which answer questions) and scan_competitor_ai_presence (which focuses on competitor scanning), making its unique function obvious.

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

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

The description gives concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model behavior plus the optional Anthropic key. While it does not explicitly list when not to use it or name alternative tools, the context is clear enough for an agent to choose this tool for visibility/awareness checks rather than other query 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, openWorldHint, idempotentHint, and destructiveHint, so the agent knows it's a safe read operation. The description goes beyond annotations by explaining the routing behavior, automatic argument filling, return format with pipeworx:// citation URIs, and performance ('one fast call'). This adds meaningful context about how the tool behaves and what the agent can expect.

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 highly structured and purposeful: domain list, operational mechanics, invocation triggers, examples, and escalation paths. It's front-loaded with 'PREFER OVER WEB SEARCH' and contains no filler. Slightly verbose but justified for a tool with such broad scope.

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 tool's complexity, the description is complete: it explains what it does, when to use it, what output to expect (structured answer with stable citation URIs), and when to choose alternatives. With rich annotations and no output schema, the description still covers the key decision points an agent needs for correct selection and 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 all parameters documented as aliases for 'question'. The description adds semantic value by providing examples and explicit guidance that any factual query is appropriate, even if web search could answer it. This helps the agent decide what to pass in the required parameter, complementing 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 what the tool does: it routes questions to the right one of 5,529 tools across 1455 sources and returns structured answers with citation URIs. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases, making the purpose unambiguous.

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

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

Usage guidelines are explicit and abundant: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE', and 'Step up only when needed' with clear alternatives. It also lists example queries, giving concrete triggers for when to invoke this tool versus others.

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, open-world, idempotent, non-destructive behavior. The description adds valuable context: it is an experimental edge, currently identical to ask_pipeworx, with no active candidate, and falls back to nothing—meaning it's a fully working router, not a stub. This goes beyond the annotations and clarifies the risk/state.

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

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

Two sentences front-load the purpose and state, then add necessary details. Every clause earns its place—no fluff, no redundancy.

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

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

For a complex routing tool with no output schema, the description explains what it does, its beta status, current identity, relationship to stable, and experimental purpose. This is complete for an agent to decide when to invoke it.

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

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

The input schema has 100% coverage and fully describes the 'question' parameter and its aliases. The description only says 'same arguments' without adding new meaning. Baseline 3 is appropriate since 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 this is a beta version of ask_pipeworx, a universal router with 5,529 tools, and explicitly distinguishes it from the stable version. The verb 'ask' combined with 'universal router' makes the function unambiguous.

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

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

The description gives explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also implies an experimental context by mentioning candidate routing improvements and comparison against stable. It does not explicitly list exclusions or alternatives like ask_pipeworx_grounded, but the context is clear.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses success/refusal return shapes, specific refusal reasons, reliance on only tool-result content, and the extra LLM call cost. This gives substantial insight into runtime behavior and failure modes without contradicting annotations.

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

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

The description is dense yet efficient. It front-loads the core value proposition, then explains routing, output structure, refusal behavior, use cases, and trade-offs against the sibling in a logical flow. Every sentence contributes meaningful information without unnecessary filler.

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

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

For a tool with no output schema, the description thoroughly covers return values, refusal reasons, cost implications, and appropriate use cases. It also situates the tool relative to ask_pipeworx. The parameter side is fully handled by the schema, so no critical context is missing.

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

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

The schema already documents all six parameters as aliases for 'question' with 100% coverage. The description adds no additional parameter-specific detail beyond implying natural-language input, so the baseline score of 3 applies because the schema carries the semantic burden.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that routes through Pipeworx, fetches data, and extracts an answer strictly from tool results. It also distinguishes itself from the sibling ask_pipeworx by noting it adds an extra LLM call, making its purpose and differentiation 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?

Explicit guidance is given: use for high-stakes reads where answers will be quoted, cited, or acted on, and avoid inventing facts in domains like financial verdicts, legal claims, medical lookups, and public statements. It also says to prefer ask_pipeworx for casual lookups, providing a clear alternative.

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

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

Annotations already flag readOnly, idempotent, openWorld, and non-destructive, but the description adds far more: resolver confidence contract, low-confidence short-circuit, blocking statuses for closed/inactive markets, GDELT fallback details, wide-spread illiquidity warnings, and cancellation-rule risk analysis. No contradiction with annotations.

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

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

The description is long but tightly structured with labeled sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, SAFETY, RESOLUTION-RULE RISK). Each section earns its place by adding a distinct behavioral constraint or return-shape detail; there is no filler or repetition despite the complexity.

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

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

With no output schema, the description takes full responsibility for explaining return values. It enumerates result.market fields, result.analysis fields, result.evidence structure, match confidence/score/alternatives, parent_event details, news fallback flags, status strings, and cancellation rules—remarkably comprehensive for a complex fan-out tool.

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

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

Schema description coverage is 100%, and each parameter (market, depth, include_raw) already has detailed explanations including defaults and response-size tradeoffs. The tool description's fan-out examples illustrate the 'market' parameter's flexibility but add little beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details the pipeline (resolve, classify, fan-out, return evidence packet) and gives explicit user intents ('should I bet on X'), clearly distinguishing this single-bet research tool from sibling arbitrage/edge 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 provides explicit usage guidance with 'Use for...' followed by concrete query types, plus classifier and fan-out examples. It does not name alternative sibling tools or state explicit exclusions (e.g., 'for arbitrage use polymarket_arbitrage'), but the scope is clear enough for an agent to select this tool for single-bet data 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?

Annotations declare readOnly/openWorld/idempotent, but the description goes far beyond by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data + citation URIs. This is substantial behavioral context 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 long but every sentence earns its place: usage triggers, preference guidance, per-type behavior, sorting, return format, and scope limits. It is front-loaded with user query patterns and maintains tight structure 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?

Despite lacking an output schema, the description explains return format (paired data + citation URIs) and ordering behavior. It covers entity types, limits (2–5), data sources, and fiscal-year handling, making the tool fully self-contained for an agent to select and invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning by explaining that type='company' pulls financial data from SEC filings while type='drug' pulls FAERS/fda/trial counts. It also gives concrete examples for the values array, which enriches what the schema alone provides.

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

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

The description opens with natural language user queries ('Compare X and Y' / 'X vs Y') and explicitly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' This clearly identifies the verb (compare) and resource (entities), and distinguishes it from sequential lookups, meeting the highest bar.

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

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

It explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' naming the alternative and specifying the condition (when comparing entities). Examples of trigger phrases provide additional context, making it clear when this tool should be invoked.

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 non-destructive, and the description adds substantial context: account/payment requirements, parallel decomposition across 5,529 tools, explicit gaps[] never-invented behavior, fetchable citation_uri, hop fields, contradictions[], semantic excerpting, and expected latency. No contradiction with annotations is present.

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?

Despite being long, every sentence adds necessary operational detail for a complex tool: prerequisites, alternatives, use cases, behavior, latencies, and caveats. The key warning and alternative are front-loaded in the first sentence, and the structure flows from account requirements to usage guidance to output semantics.

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 thoroughly covers what the agent will receive: a findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop fields, and citation_uri semantics. It also specifies timing and edge cases like missing structured-catalog topics, making the description complete for the tool's complexity.

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

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

Schema coverage is 100% for its 2 parameters, and the description adds significant semantic value beyond the schema: it explains how depth values map to hop counts, gap recovery, contradictions scanning, and paid requirements, and clarifies that the question parameter accepts broad natural-language multi-part questions.

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

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

The description clearly identifies the tool as 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with concrete examples of use cases. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx.

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

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

The description gives explicit when-to-use guidance: best for broad/multi-part structured-data questions, prefer ask_pipeworx for single lookups or breaking/current news, and use ask_pipeworx if not signed in. It also explains depth tiers and when thorough vs standard is appropriate.

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

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

Annotations already mark it read-only and idempotent. The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotation safety profile and explains the response nature.

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: purpose, when-to-use with domain list, and return behavior. Each sentence earns its place, is front-loaded, and has no filler or redundancy. Extremely efficient for a meta-tool description.

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

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

Even without an output schema, the description fully explains the return value (names, descriptions, full input schemas) and the intended use case. For a tool-discovery tool, this is complete: it covers how it behaves, what it returns, and when to invoke it. No obvious gaps for the agent to select and call it correctly.

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

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

Input schema coverage is 100% with every parameter (including aliases) described. The description does not add new parameter-level details; it only mentions 'top-N' which corresponds to the existing 'limit' parameter. Baseline 3 is appropriate since schema handles the semantics.

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

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

The description starts with a specific verb and resource: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling tools like search_* or ask_pipeworx by focusing on discovering tools rather than operating on data. The list of domains further clarifies the intended scope.

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

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

Explicit when-to-use guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This also implies when not to use it (when you already know the specific tool and want a single answer).

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds substantial behavioral context: fan-out across multiple sources, specific return fields, patent API sunset with soft-fail, and GDELT→GNews fallback. This goes far beyond what annotations convey.

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

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

The description is long but front-loaded with trigger phrases and a clear usage directive. It packs useful details about return fields, fallbacks, and constraints into one dense paragraph. Every sentence adds functional value, though it could potentially be split into sections 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 no output schema, the description does a solid job of enumerating return categories (filings, fundamentals, patents, news, LEI) and caveats. It covers prerequisites and failure modes, but exact output structure for each returned category (e.g., news or LEI) is left vague. Sufficient for an aggregator tool.

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

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

Schema description coverage is 100%, with both parameters (type and value) already well described, including enum details and zero-padded CIK examples. The description largely repeats this information without offering new parameter-level semantics, so the baseline 3 applies.

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

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

Description clearly identifies the tool as a holistic cross-source profile generator for US public companies, with explicit query examples and a strong 'ALWAYS PREFER' directive. It distinguishes from chaining single-pack lookups and references resolve_entity for name-only inputs, but it doesn't explicitly contrast with sibling tools like compare_entities or deep_research.

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

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

The description explicitly states when to use the tool: for holistic views of a public company ('Tell me about X', 'brief me on Tesla'), and to prefer over chaining single-purpose lookups. It also gives exclusions: names are not supported, and directs users to resolve_entity first. This is clear, actionable 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 destructiveHint and idempotentHint. The description adds the specific resource destroyed (a memory by key) and the sensitive-data clearing use case, which goes beyond the annotation hints. No contradiction.

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

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

Three concise sentences that efficiently cover the action, usage guidance, and relationship to sibling tools. No redundant or filler 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?

For a one-parameter destructive operation, the description fully covers purpose, usage conditions, and tool relationships. Annotations handle safety hints, and the schema covers parameter detail, leaving no significant gaps for an agent to 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?

The input schema fully covers the 'key' parameter with a clear description. The tool description only mentions 'by key' without adding new semantic detail, so it meets the schema-coverage baseline but does not exceed it.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb and resource. It also distinguishes itself from siblings by mentioning pairing with 'remember' and 'recall', making its role in the memory workflow unambiguous.

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

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

Provides explicit usage conditions: use when context is stale, the task is done, or when clearing sensitive data. It also indicates alternatives by pairing with 'remember' and 'recall', signaling when not to use this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable process details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations without contradicting 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?

Three well-structured sentences: purpose, method, and use cases. Each sentence adds distinct value and is front-loaded with the core function.

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

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

Given the 2-parameter schema, no output schema, and rich annotations, the description fully covers what the tool does, how it behaves, what it returns, and when to use it. It explains the output format and practical applications clearly.

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 descriptive parameter definitions. The description adds no extra parameter details beyond what the schema already provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the exact output format. It distinguishes itself from siblings by focusing on llms.txt generation rather than AI visibility scanning, despite the competitor-auditing use case.

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 use cases (getting a client indexed, drafting for own project, auditing competitor AI view) but does not name alternative tools or state when not to use it. This gives clear context but lacks exclusion/alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by specifying the return fields and the default behavior (active-only, with include_inactive to include cancelled). No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the verb and resource. Every word earns its place, with no redundancy or fluff.

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

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

There is no output schema, but the description lists all returned fields (id, type, params, created_at, last_fired_at, fire_count), which is essential for understanding the response. For a simple list tool with one optional parameter, it is sufficiently 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?

The schema fully documents the single parameter (include_inactive) with a clear description, achieving 100% coverage. The tool description merely echoes the default active-only behavior, adding no significant meaning beyond the schema.

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

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

The description uses a specific verb ('List') and clearly identifies the resource ('the caller's active subscriptions'). It distinguishes from sibling tools like subscribe/unsubscribe by focusing on reading subscriptions rather than modifying them.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This gives clear guidance on when to use, though it doesn't explicitly name alternative tools like subscribe or unsubscribe.

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

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

Despite annotations providing no help (all false), the description discloses critical behaviors: the claim_token mechanism for later status checks, rate limiting ('5 per identifier per day'), cost/quotas ('Free; doesn't count against your tool-call quota'), and processing cadence ('reads digests daily'). It also warns against pasting end-user prompts, adding operational context well beyond what annotations offer.

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

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

The description is longer than average but every sentence serves a purpose: identifying the action, giving use cases, defining scope boundaries, describing the token workflow, and noting constraints. It is front-loaded with the primary function and then logically flows into usage details. No filler or redundancy.

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

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

Given the tool's moderate complexity (4 params, nested context object, no output schema), the description covers all necessary context: what to submit, scope restrictions, behavioral details, rate limits, and the follow-up token mechanism. It fully equips an agent to decide when and how to 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 coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema: it explains how claim_token is used to read previous reports and gives an example call format (pipeworx_feedback({claim_token:"pwfb_…"})). This adds practical value not present in the schema.

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

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

The description opens with a clear verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists the feedback categories (bug, feature/data_gap, praise), which distinguishes it from sibling tools like ask_pipeworx or research tools. This is a specific, unambiguous purpose.

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

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

The description provides explicit when-to-use conditions ('Use when a tool returns wrong/stale data... feature/data_gap... praise') and a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance with a named alternative action.

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

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

With annotations already declaring safe read-only behavior, the description adds valuable context: caching (5min-1h), no PII, and derivation from CF analytics-engine. It explains the self-aggregating nature and that it only contains (pack, tool, count) information, which goes beyond the annotations. No behavioral traits are omitted that matter for a read-only trending query.

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

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

The description is front-loaded with the core purpose, then lists use cases and technical notes efficiently. Every sentence earns its place without redundancy. It is slightly longer than necessary but well-structured, avoiding 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 simplicity (one optional parameter, no output schema), the description fully covers what it returns (top tools, packs, count), the window semantics, caching caveats, and privacy guarantees. The use-case list adds operational context. It is complete for an agent to invoke correctly without needing additional information.

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

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

The only parameter 'window' is fully described in the schema (100% coverage), including the same explanation about shorter vs longer windows. The tool description does not add new meaning beyond the schema, so the baseline of 3 is appropriate. It repeats the default value (24h) but adds no extra syntax or format details.

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

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

The description states a specific verb ('returns') and a precise resource: 'top tools, top packs, and total call volume over a recent window.' It clearly distinguishes this from sibling tools like discover_tools by focusing on what other AI agents are calling, which is unique. The purpose is immediately clear and unambiguous.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. It also gives guidance on window selection ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). However, it does not mention alternatives or when not to use this tool, lacking exclusion guidance.

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

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

Beyond the read-only and idempotent annotations, the description discloses algorithmic details (Jaccard ≥0.30 similarity, >3pp deviation threshold, >20% placeholder filtering), response structure, and the fill-check step distinguishing theoretical vs realizable edge. It even provides a 'do not trade it' rule when realizable_edge_pp ≤ 0, giving the agent actionable behavioral guidance.

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 front-loaded with the core purpose and structured by mode. Every sentence adds operational detail (thresholds, examples, fill-check warning) that is necessary for this complex tool. No redundant phrases are present; the density is justified.

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

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

The tool has no output schema, but the description fully explains the response fields (opportunities[] with gap_pp, suggested_trade, reasoning, partition_check details) and the fill-check output. It also covers edge cases like skipped_low_similarity and null arb signals, making the description complete for an agent to invoke 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?

Even with 100% schema coverage, the description adds substantial meaning: example event slugs and topic seeds, the behavior when no args are passed, and the internal logic each parameter triggers. It clarifies that event is the recommended mode for specific markets and topic for cross-event scanning, going well beyond the schema's basic field descriptions.

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

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

The first sentence states the purpose precisely: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between event and topic modes and differentiates from polymarket_fill_risk for custom sizing, establishing a unique resource and mechanism.

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

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

The description provides explicit when-to-use guidance: no args for trending_scan, 'event' recommended for a specific market, 'topic' for cross-event scanning. It also explains why to choose one mode over the other (cross-event catches patterns single-event misses) and directs users to polymarket_fill_risk for custom sizing, satisfying the alternatives requirement.

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

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

The description goes far beyond annotations by disclosing caching behavior ('Cached 1h at the KV level'), internal model families and their formulas, structural details like the placeholder-slug filter, and special cases like 'Partition arbs always return kelly_fraction_half=0 at the parent level by design.' It also warns about 24h market moves potentially pricing in the edge. These are valuable behavioral insights not derivable from readOnlyHint or idempotentHint.

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

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

The description is extremely long and dense, with detailed formulas and per-sport α values. While it is structured into segments and knobs, it reads as a wall of text that could be overwhelming. It is front-loaded with purpose but then dives into extensive model internals that may exceed what an agent needs for tool selection. Appropriately sized would be more concise.

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

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

Given there is no output schema, the description thoroughly documents the response top-level (by_segment, fed_candidates, _diagnostics) and explains why segments may be empty. It covers all 9 parameters through schema plus additional narrative. It also notes tradeable-edge knobs and caching. This is complete enough for an agent to invoke and interpret results confidently.

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% parameter descriptions, so the baseline is 3. The description adds extra semantics beyond the schema: it explains how min_kelly interacts with partition_overround (parent-level kelly always 0), why min_partition_leg_kelly exists specifically for per-leg filtering, and clarifies slippage assumptions (zero fees but 20-50bp bid/ask). This adds real value.

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

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

The description opens with a specific verb+resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from siblings like polymarket_arbitrage (focused on arbitrage) and polymarket_edge_tracker (tracking edges over time). The 'what should I bet on today' use case further clarifies the tool's niche.

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

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

Explicit usage context is provided: 'Built for what should I bet on today' and notes agents use it to avoid paging hundreds of markets. It also explains when certain knobs should be adjusted (e.g., max_spread_pp, min_liquidity) and why Fed bets are excluded from ranking. However, it doesn't name sibling tools as alternatives, so it doesn't fully distinguish when to use this vs polymarket_arbitrage or polymarket_fill_risk.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description complements these with rich behavioral detail: response structure (tracked[], expired[], snapshot_dates[]), snapshot generation on cache-miss (gaps mean no scan), history depth bounded by 60-day TTL, decay computed from daily closes not intraday, and edge sign conventions. 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 dense but extremely well-structured with labeled sections: purpose, args, response contract, and limitations. Every sentence conveys essential information—no fluff or redundancy. It front-loads the core question and then details response fields and caveats efficiently.

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

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

Even without an output schema, the description fully specifies the response shape (tracked[], expired[], snapshot_dates[] with field meanings), explains data provenance and gaps, and covers limitations (TTL, decay basis). This is complete enough for an agent to select and invoke the tool correctly without external documentation.

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 days and window are fully described in the input schema. The description restates defaults and adds the phrase 'snapshot family' but does not add significant new meaning beyond what the schema already provides. Baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It clearly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from siblings like polymarket_edges by focusing on historical persistence/decay 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?

It gives clear context for when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades.' It explains the response includes expired opportunities as a competition clock, and notes limitations like snapshot TTL. However, it does not explicitly name alternatives or exclusion criteria, so a full 5 is not earned.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses substantial behavioral traits: it walks the order-book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and shares_filled, and warns about forced_directional_risk. It also explains the consequences of partial basket fills, providing context annotations alone do not convey.

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

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

The description is long but front-loaded with the core purpose and structured by mode (SINGLE-MARKET, BASKET). Given the absence of an output schema, listing return fields is necessary. While it could be tightened slightly, every sentence earns its place, and the organization aids readability.

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

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

The tool has two modes, four optional parameters, and no output schema. The description fully covers both modes, parameter interpretations, return values (theoretical_sum, capture_ratio, thin_legs, etc.), and usage context. It also addresses failure modes and risk, making it complete for an agent to decide when and how to 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?

Although schema coverage is 100%, the description adds significant semantic depth. For size_usd, it distinguishes between single-market ('max spend on buys, target proceeds on sells') and basket ('settlement notional S — shares per leg'). It also explains the side parameter's mode-dependent defaults and auto behavior based on partition sum, enriching the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly positioning itself as a pre-trade validation check. The verb 'check' plus the resource 'CLOB order-book depth' makes the function unambiguous.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains two distinct modes (single-market vs. basket) and when each applies, including the rationale that theoretical overround on thin books is not capturable and partial basket fills can create unhedged directional risk.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed behavioral traits: compatibility_warning cases (matched_pairs:0 with skipped_cross_type>0 vs without), temporal_alignment consequences, and skipped_cross_type/subtype counters. It explains what the tool does and does not validate, exceeding annotation coverage.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every sentence adds value, such as the concrete list of shortcuts and the practical caution about rare tradeable spreads. No filler.

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

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

Given no output schema, the description compensates by explaining output components (leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It addresses edge cases (non-equivalent bet shapes, unrelated events) and resolves how to interpret results, making it highly 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 each parameter has a description, so baseline is 3. The tool description adds meaning about parameter interaction: 'topic' auto-fetches 10 shortcuts, while explicit tickers override mapped sides. It also clarifies the response structure tied to parameters, adding value beyond schema.

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

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

The description opens with a clear verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes this tool from siblings by emphasizing spread rather than arbitrage or edges, and the explicit mention of compatibility warnings and temporal alignment adds specificity.

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

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

Provides explicit usage guidance: two modes ('topic' auto-fetch vs explicit tickers/slugs), and warns 'pre-mapped ≠ tradeable.' It does not explicitly name alternative tools, but the context is clear and includes cautions about when spreads are meaningful vs not.

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

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description adds valuable context beyond that: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and the dual-mode behavior of omitting the key to list all keys. These are meaningful behavioral disclosures not present 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 four sentences, each with a distinct purpose: the core action, usage context, scoping, and companion workflow. It is front-loaded with the primary action and contains no redundant or filler 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?

For a simple tool with one optional parameter and no output schema, the description sufficiently explains the return behavior (value or list of keys), scoping, and how it fits with remember and forget. The agent has enough context to select and 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 description restates the schema's parameter description ('omit the key argument' matches the schema's 'omit to list all keys'). Schema coverage is 100%, so the baseline is 3; the description adds no extra format or syntax details for the key parameter.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys'. It clearly distinguishes from siblings by referencing remember and forget, and provides concrete usage examples ('user's target ticker, an address, prior research notes').

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

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

It gives a clear when-to-use: 'Use to look up context the agent stored earlier — the user's target ticker, an address, prior research notes — without re-deriving it from scratch.' It also pairs with companions ('Pair with remember to save, forget to delete'), but does not explicitly state when not to use or list alternative tools for the same purpose.

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

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

The description reveals that setting mark_read:true modifies state (flags events as read), which directly contradicts the annotation readOnlyHint:true. Even though the description is transparent about this side effect, it conflicts with the structured hint, so this is an annotation contradiction.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by return fields, filtering options, side-effect behavior, and an alternative access method. Every sentence earns its place 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 there is no output schema, the description compensates by listing return fields (source, citation_uri, raw payload). It covers filtering, mark_read side effects, and polling guidance. It doesn't mention limit or unread_only, but those are documented in the schema, so the description is adequately 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?

While schema coverage is 100%, the description adds meaning by giving an example for type (sec_8k), clarifying since is an ISO timestamp, and explaining the consequence of mark_read (next call only shows newer events). This goes beyond the brief schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed, using the specific verb 'Pull' and naming the resource. It distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing on the alert feed.

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

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

The description provides clear context for when to use the tool, noting that polling works fine and offering the alternative GET endpoint for scripts/dashboards. While it doesn't explicitly mention sibling tools as alternatives, the guidance is sufficient for typical use cases.

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

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

Beyond the readOnly and non-destructive annotations, the description discloses that the tool fans out to multiple external APIs (SEC EDGAR, GDELT/GNews, USPTO) and even notes the USPTO PatentsView sunset and soft-fail behavior. This gives the agent important context about potential external dependencies and failure modes.

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

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

The description is dense but well-organized, starting with query intents and moving to functional details and alternatives. While somewhat long, every sentence provides useful information, and the key points are front-loaded.

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

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

With no output schema, the description fully describes the return shape (changes[] grouped by source, total_changes count, citation URIs). It also covers parameter formats, external data sources, fallback logic, and an explicit sibling alternative, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: it explains the 'since' parameter accepts ISO dates or relative shorthand with concrete examples, and clarifies 'value' can be a ticker or zero-padded CIK. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, aggregating filings, news, and patents. It distinguishes itself from the sibling entity_profile tool by explicitly directing users who want a static profile to that alternative.

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

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

The description gives explicit guidance on when to use this tool (e.g., 'What's new with X') and when to use entity_profile instead. It also explains internal fallback behavior (GDELT to GNews) and typical parameter values, making usage context 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?

Beyond the annotations (which already indicate idempotent, non-destructive), the description adds meaningful behavioral context: memory is scoped by identifier, persistence varies by auth status (persistent vs 24 hours), and values are stored as key-value pairs. This enriches the agent's understanding of side effects, though it doesn't detail overwrite behavior, a minor gap.

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 (four sentences) and front-loaded with the core purpose. Each sentence provides necessary information—purpose, use cases, storage semantics, persistence, and related tools—without unnecessary fluff.

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

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

For a simple 2-parameter tool with no output schema and good annotations, the description covers all essential aspects: what to save, when to use it, how it's stored, persistence conditions, and pairing with related tools. It is sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with both key and value already described. The description adds a bit of context by reinforcing the key-value scoping and giving examples of value content (e.g., 'resolved ticker, target address'), but it doesn't substantially extend the schema's meaning.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Save data the agent will need to reuse later.' It distinguishes itself from siblings by mentioning 'Pair with recall to retrieve later, forget to delete,' making its role in the memory workflow 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 guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names related tools (recall, forget) and their purposes, helping the agent choose the right tool.

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

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

The description adds substantial behavioral context beyond the annotations: identifiers that cannot be resolved are explicitly listed under `unresolved` rather than omitted, every identifier is source-labelled, and LEI/FIGI enrichment degrades gracefully if external sources are unavailable. These details describe output behavior and fallback logic not covered by the readOnly/idempotent hints.

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

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

The description is longer than average but well-structured, starting with example queries, then the core purpose, supported types with details, and graceful degradation. Every section adds useful information, and the length is justified by the tool's complexity. It could be slightly trimmed, but overall it is efficient and front-loaded.

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

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

Without an output schema, the description thoroughly explains what the tool returns for both entity types: for company, it lists CIK, ticker, company_name, LEI with ownership, and FIGI, with source labels and unresolved handling; for drug, it mentions RxCUI, ingredient, brand, and a citation link. It also covers fallback behavior, making it complete enough for an agent to know what to expect.

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

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

The input schema already documents both parameters with examples and enums, covering 100% of parameter semantics. The description's parameter-related text ('For company: ticker...') essentially repeats the schema without adding new constraints or context. Thus it adds no value beyond the structured definition.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also includes explicit usage guidance, 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools like entity_profile.

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

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

The description provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that 'using resolve_entity replaces 2-3 manual lookups,' reinforcing its efficiency advantage over alternative workflows. While it doesn't list exclusions, the context is clear.

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

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

Annotations already cover readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: it probes each entity internally, ranks by score, and returns score/confidence/signal density per entity. This goes beyond annotations and helps set expectations about the multi-step nature and output. No contradictions.

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

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

The description is three sentences long, each sentence earning its place: the first states purpose, the second explains method and use case, the third describes output. It is front-loaded with the core action and contains no fluff or 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?

Since there is no output schema, the description appropriately explains the return format (ranked list with score, confidence, signal density). It also covers the workflow and intended use case. Minor gaps like not mentioning potential cost of multiple model probes or entity constraints beyond the schema are acceptable, but overall it is reasonably 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% for all four parameters, so baseline is 3. The description adds meaning beyond the schema by stating 'First entry treated as the "subject" for narrative; rest are competitors.' This clarifies the role of the first entity, which is not obvious from the parameter description 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 'Compare AI visibility across multiple entities side-by-side', specifying the verb 'compare' and resource 'AI visibility'. It distinguishes from the sibling tool ai_visibility_check by emphasizing the multi-entity side-by-side comparison, and from compare_entities by focusing specifically on AI visibility with ranking.

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

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

It provides a concrete use case ('competitive AI-marketing audits') and an illustrative question, making when to use it clear. It also implies the difference from ai_visibility_check by saying 'Probes each entity with ai_visibility_check', suggesting this is the multi-entity version. However, it does not explicitly state 'when not to use' or name alternatives, though the context is 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?

Beyond the annotations (readOnly, idempotent), the description discloses important behaviors: it fans out across multiple services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will identify timeouts. This adds genuine context not available 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 longer than two sentences but is well-structured and front-loaded with the core purpose ('Composite... in ONE call'). It includes a detailed list of return fields, which is necessary given no output schema. Each sentence contributes useful information, though it could slightly be more compact.

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 thoroughly explains return values (summary block fields, per-advisory detail, links, recent alternatives), failure behavior, ecosystem limitations, and potential latency. It is complete for an agent to know what to expect and how to handle edge cases.

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 has 100% coverage with descriptions for both parameters. The description does not add the parameter semantics beyond what the schema provides (e.g., default version behavior is already in the schema). Baseline 3 is appropriate as the description adds no extra meaning.

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

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

The description clearly states the tool's purpose: a composite check for evaluating whether to add an npm package, combining data from deps.dev and bundlephobia. It uses specific verbs ('scan', 'check') and explicitly distinguishes itself by the composite nature and NPM-only scope.

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

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

The description provides explicit usage triggers: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. It also names an alternative for non-NPM ecosystems ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), giving 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context by stating 'Keyless' (auth not required) and listing the exact return fields (name, location, continent region, member network count, website), which is especially valuable given the absence of an output schema.

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

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

The description is three concise sentences, front-loaded with the verb and resource, followed by output details and a usage requirement. Every sentence adds value with no redundancy or fluff.

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

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

For a read-only search tool with full schema coverage and robust annotations, the description is complete enough. It communicates the search criteria, required input constraint, return fields, and keyless access. There is no output schema, but the listed return fields suffice for this straightforward tool.

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

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

The input schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds a cross-parameter constraint not captured by the schema: 'Provide at least one of query/city/country.' This is a meaningful semantic addition that helps ensure correct invocation.

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

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

The description clearly states the tool's function: 'Find internet exchanges (IXes) in PeeringDB by name, city, or country' and lists the returned fields. This distinguishes it from sibling search tools like search_facilities and search_networks by specifying the exact resource (IXes).

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 usage context: it searches by name, city, or country, and explicitly requires 'at least one of query/city/country.' It also notes the tool is 'Keyless,' indicating no API key is needed. However, it does not mention when not to use this tool or alternatives like search_facilities or search_networks.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is clear. The description adds extra behavioral context by listing the return fields ('facility name, location, network count, street address, and website') and noting 'Keyless' (no API key required), 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 two sentences with no unnecessary verbiage. The first sentence front-loads the core purpose and search criteria, and the second sentence covers return values and the input requirement, making it efficient and 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?

For a search tool with 4 parameters and no output schema, the description provides essential context: what it returns, the input requirement, and the keyless nature. It does not cover pagination or sorting, but the limit parameter is in the schema, so the description is reasonably complete for its complexity.

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

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

The input schema provides 100% coverage with descriptions for all parameters. The description adds semantic value by specifying that at least one of query/city/country is required and clarifying that query matches facility names, which reinforces and extends the schema information.

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 specific action and resource: 'Find colocation facilities (data centers) in PeeringDB by name, city, or country.' It distinguishes this tool from sibling search tools like search_networks and search_exchanges by specifying the facility type and data source.

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

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

The description provides explicit usage guidance: 'Provide at least one of query/city/country.' It implies the tool is for facility searches, giving clear context for when to use it, though it does not explicitly mention alternatives or 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 provide readOnlyHint, openWorldHint, idempotentHint, and non-destructive hints. The description adds transparency by specifying 'Keyless' (no auth) and enumerating the exact output fields (peering policy, traffic level, info type, scope, prefix counts), which is useful beyond the annotations. It does not contradict annotations.

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

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

The description is appropriately concise: two sentences with no fluff. It front-loads the purpose, then states key output fields and input requirements. Every clause adds information, and the keyless note is a compact way to convey authentication status.

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 absence of an output schema, the description compensates by listing the returned attributes. It covers the purpose, input requirements (currently query/ASN), and the data returned, making it self-contained. It is complete enough for a search tool, especially given the rich annotations and parameter descriptions.

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

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

The schema covers all three parameters with descriptions, so the baseline is 3. The description adds meaning by indicating that query and ASN are alternative inputs ('Provide a name query or an ASN'), which clarifies their relationship. It also notes 'Keyless' implicitly affecting usage, but the main added value is the mutual exclusivity hint.

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 lookup for PeeringDB networks by name or ASN, with a specific verb ('Look up') and resource ('networks in PeeringDB'). It also lists the returned attributes, which distinguishes it from sibling search tools like search_exchanges or search_facilities.

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

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

The description provides clear context on how to invoke the tool: 'Provide a name query or an ASN' and 'Keyless' indicates no authentication prerequisites. It does not explicitly mention alternative tools, but the coverage of input modes is clear. Since no exclusions or when-not-to-use guidance is given, it gets a 4 rather than 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses concrete technical behavior: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap, and truncation flagging. It also clarifies output includes character offsets and similarity scores, which annotations don't cover.

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 yet efficient, organizing content into distinct clauses: core function, use case, sibling integration, and technical constraints. No wasted words; every sentence contributes unique 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?

For a tool without an output schema, the description explains return values (passages with offsets and similarity scores), constraints (200K cap, truncation flag), and interplay with the gateway tool. It gives enough for an agent to invoke correctly and verify 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?

The input schema already documents all three parameters with descriptions, achieving 100% coverage. The description adds contextual meaning by defining 'text' as a fetched record with examples (SEC 10-K, article) and clarifying the query is natural-language, enhancing the schema without repeating it.

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

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

The description specifies 'Semantic search INSIDE a fetched record' with a clear verb and resource, and differentiates from siblings by requiring already-pulled text. It explicitly mentions returning top-N passages with offsets and scores, making the tool's function unambiguous.

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

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

The description states 'Use when the record is too big to cram into the prompt' and 'saves context, returns only the passages that matter,' providing explicit guidance. It also names the alternative ask_pipeworx_grounded and explains the pairing, offering clear 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?

The description adds substantial behavioral details beyond annotations: OAuth requirement, feed always on, SMS verification and 10/day cap, webhook signing secret returned once, and auto-disable after 10 consecutive failing runs. This greatly enriches the agent's understanding of side effects and prerequisites.

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

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

The description is dense but well-structured, front-loaded with the core purpose and then organized by type and delivery channel. No sentences are superfluous; though long, it is efficient for the complexity involved.

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

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

Given the tool's complexity and absence of an output schema, the description covers prerequisites, examples for all types, delivery mechanics, and key response elements (subscription id, webhook secret). Minor gap: it doesn't describe the full response object beyond those two items, but it is sufficient 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 includes type-specific parameter structures, so baseline is 3. The description adds semantic meaning with concrete examples (e.g., items:["5.02"] = officer change) and explains the purpose of each subscription type, pushing it above baseline.

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

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

The description clearly states the tool's function: "Create a proactive monitoring subscription to a live-data event stream" and specifies the return value. It distinguishes itself from siblings like unsubscribe and list_subscriptions by focusing on creation and providing supported subscription 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?

It provides clear usage context: requires a Pipeworx OAuth account, and suggests alternatives for data retrieval ("feed (always on — pull via recent_alerts or GET registry.pipeworx.io/alerts.json)"). However, it does not explicitly state when not to use it or compare with related monitoring tools, so it's 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.

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

Annotations (readOnlyHint, idempotentHint, openWorldHint) already cover safety. The description adds behavioral context by explaining the return structure (category-bucketed example questions) and that the catalog is 'live', implying dynamic content. It does not mention potential length or pagination, but the core behavior is transparent.

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

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

The description is front-loaded with user-like example queries, then explains the return value, then invocation modes, then when to use. Every sentence adds critical information; no filler. The length is justified by the richness of 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?

Despite no output schema, the description thoroughly covers the return value (categories and exact tool+argument shapes), usage patterns (no args vs. topic), and relationship to meta-tools. For a discovery tool with this complexity, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, and the description enriches the `topic` parameter with explicit examples ('finance', 'pharma', 'betting') and the effect of omission ('full spread'). This goes beyond the schema's simple 'Optional focus area' 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 a specific verb ('Returns category-bucketed example questions') and clearly identifies the resource ('Pipeworx') and scope ('onboarding entry point'). It distinguishes from siblings like discover_tools by emphasizing question suggestions with exact tool+argument shapes, not just tool discovery.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternatives (meta-tools like ask_pipeworx, entity_profile). It also offers concrete invocation guidance: 'Call with no arguments... or pass `topic` to focus.'

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, the description discloses that ownership is enforced, the row is deactivated not deleted, and historical events remain accessible through recent_alerts. This adds meaningful behavioral context consistent with the idempotent and non-destructive hints.

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

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

Two sentences, front-loaded with the action, and no wasted words. Every clause adds useful information about ownership and deactivation behavior.

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

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

For a simple one-parameter cancellation tool with annotations indicating idempotency and non-destructiveness, the description covers the key behavioral caveats and historical-data impact. No output schema is needed for this action.

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

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

The schema already fully documents the single 'id' parameter as a subscription uuid returned by subscribe. The description merely says 'by id' and adds no further parameter-level meaning, so baseline 3 applies.

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

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

The description opens with 'Cancel a subscription by id,' using a specific verb and resource. It distinguishes itself from siblings like subscribe and list_subscriptions by clarifying this is the cancellation action.

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

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

The description gives clear context: ownership is enforced and the row is deactivated rather than deleted, with historical events still available via recent_alerts. It does not explicitly name alternatives like list_subscriptions, but the ownership and historical-event guidance make when to use this tool 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses critical behavior: the difference between 'could_not_verify' and 'unsupported', that 'could_not_verify' carries verification_error and must not be used as evidence, and that the tool replaces multiple sequential calls. This is substantial context that annotations do not cover.

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

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

The description is longer than average but dense with useful information. It front-loads examples and a clear purpose, then adds routing, return format, and an important caller caveat. Some repetition (e.g., listing multiple phrasings) exists, but it serves the purpose of intent matching. Overall well-structured and each 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 complex tool with no output schema, the description explains the verdict values, the return payload (value with citation and reasoning), the error semantics, and the distinction between 'could_not_verify' and 'unsupported'. It even mentions performance benefits (replacing 4–6 calls). This is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100%, with both parameters (claim and tolerance_pct) fully described. The description adds some context about exact percent-delta math for financial claims, but does not elaborate on parameter syntax or semantics beyond what the schema already specifies. 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 states a clear, specific action: natural-language claim verification against authoritative sources, with a defined verdict set. It opens with user-phrasing examples ("Is it true that…", "fact check") and explicitly names the tool's role as checking factual statements, distinguishing it from sibling tools like ask_pipeworx or search_exchanges.

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

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

The description gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further partitions use by claim type (company-financial vs any other) with routing logic. However, it does not name alternatives or explicitly state when not to use, so it falls short of the top tier.

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