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 cover read-only, open-world, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: it routes across thousands of tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. This goes beyond the 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?

The description is somewhat long but well front-loaded with the most important guidance ('PREFER OVER WEB SEARCH'), followed by supported domains, examples, and routing alternatives. Each section earns its place, and the examples are varied and concrete rather than redundant.

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

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

With no output schema, the description adequately explains the return format: a structured answer with stable citation URIs. It covers expected inputs through examples, clarifies when to use this tool versus web search and deep_research, and relies on annotations for safety. Minor gaps like error behavior or authentication are not critical for this kind of read-only routing 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%, so the parameter semantics are already fully documented in the schema. The description adds useful example questions and trigger phrases, but it does not provide additional parameter-level detail beyond what the schema already gives. Baseline 3 is appropriate.

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

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

The description clearly states the tool's function: routing a natural-language question to the right one of 5,767 tools across verified sources and returning a structured answer with stable citation URIs. It also distinguishes it from web search and from deep_research, making the tool's unique role immediately clear.

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

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

The description gives explicit when-to-use guidance: prefer this over web search for factual questions about real-world data, use it whenever the user says 'what is', 'look up', 'find', 'get the latest', etc. It also names the alternative deep_research for broad/multi-part questions, and clarifies that breaking-news questions are already handled here.

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, the description discloses important live behavior: candidate routing improvements are enabled only when under test, no candidate is currently active, and the last was retired on 2026-07-26. It also clarifies that there is no fallback behavior and that results are compared against the stable router. This is substantial behavioral context that the annotations do not provide.

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

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

The description is information-dense and front-loaded with the key identity ('Beta version of ask_pipeworx'). Each sentence contributes useful context, but there is slight redundancy between 'No candidate is active right now' and 'so this currently matches ask_pipeworx exactly'. Minor redundancy aside, it is still well-structured and not bloated.

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 question-routing tool with one required parameter, the description covers identity, behavioral state, comparison to the stable sibling, current equivalence, and lack of fallback. It also states the response shape matches ask_pipeworx, compensating for the absent output schema. No critical information for selecting or invoking the tool correctly is missing.

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

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

Schema coverage is 100%, so the parameters are already well documented, including the alias relationships for question. The description adds that the tool accepts 'same arguments' as ask_pipeworx and should be used exactly like it, which provides mild cross-tool context but does not need to repeat the schema. This meets the baseline for schema-covered parameters.

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

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

The description identifies the tool as a 'Beta version of ask_pipeworx' and a 'universal router' with 'the same 5,767 tools, same arguments, same response shape', which makes its role clear. It also distinguishes it from the stable ask_pipeworx by emphasizing the experimental edge. It stops short of explicitly stating the core action ('route a natural-language question'), but the title and schema make that reasonably inferable.

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 tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also clarifies that the stable router is the comparison baseline, implying the stable tool is the alternative for normal use. The current state ('No candidate is active right now... this currently matches ask_pipeworx exactly') gives concrete routing 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 readOnly/openWorld/idempotent annotations, the description reveals critical behavioral traits: it returns either a success object with evidence/confidence/source/fetched_at or an explicit refusal with a specific refusal_reason. It also states that the tool 'EXTRACTS the answer using ONLY what the tool result contains,' making its non-inventiveness guarantee explicit.

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

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

The description is dense but every sentence earns its place: it covers routing, grounding behavior, return/refusal shapes, usage conditions, and cost tradeoff. It is front-loaded with the core value proposition and does not repeat structured annotation information.

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

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

Given there is no output schema, the description fully compensates by spelling out the success shape, refusal shape, and all refusal reason enum values. It also provides routing context, cost tradeoff, and use-case boundaries, leaving no significant gap for an agent deciding or invoking 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 already covers all six parameters at 100% and clearly documents them as aliases for the single 'question' parameter. The description does not need to add parameter detail, so the baseline of 3 applies; it neither enhances nor reduces schema clarity.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads,' which is a specific verb (answer/ground) plus resource (pipeworx tool results). It also distinguishes itself from ask_pipeworx by stating it follows the same routing but extracts answers only from tool-result content.

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 tells the agent when to use this tool: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts, legal claims, and medical lookups. It also names the alternative (ask_pipeworx) and gives a clear preference rule: prefer ask_pipeworx for casual lookups because this mode costs an extra LLM call.

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

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

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/idempotent/openWorld, so the bar is lower, but the description adds substantial behavior beyond them: account/paywall requirements, the guarantee that gaps[] are 'never invented', the parallel decomposition into 5,767 tools, latency expectations (15-60s, ~90s for thorough), citation_uri being present only when actually fetchable, and semantic excerpting rather than head-truncation. 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?

Dense but every sentence earns its place — no filler. It's front-loaded with the account requirement. Penalized slightly for being a single wall-of-text paragraph with no bullets or paragraph breaks, and for a mild redundancy where the citation_uri/fetchable guarantee is stated twice. Otherwise efficiently packed.

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

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

No output schema exists, so the description correctly carries the burden of explaining return values: findings packet with verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers prerequisites, timing, limitations, and alternatives. Nothing an agent needs to invoke this complex tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters; baseline is 3. The description adds real value on top: that depth:'thorough' requires a paid plan, clarifies the gap-recovery/contradictions behavior per depth level, and explains that the question param can be broad/multi-part because 'decomposition is the point'. This exceeds the baseline but doesn't add syntax-level detail the schema lacks.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' in one call. It sharply distinguishes from siblings by explicitly saying 'this is NOT open-web search' and naming ask_pipeworx as the alternative for single lookups, so an agent can tell them apart without opening schemas.

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

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

Gives explicit when/when-not guidance with named alternatives: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also states what it is best for ('broad/multi-part questions over structured data') with concrete example queries.

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

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

Annotations already 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description reveals important behavioral traits: one parallel fan-out call, USPTO soft-fail after May 2025, empty sections meaning genuine absence of data rather than failure, resolved_from/resolved_to behavior, and the explicit notes line for private companies. This is substantial context beyond the structured annotations and contradicts nothing.

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 examples and a clear preference directive before diving into output structure. Every section earns its place: input shapes, fan-out sources, output fields, edge cases, and empty-data semantics are all covered without repetition or filler.

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

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

There is no output schema, so the description fully carries return-value documentation: it enumerates resolved metadata, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed. It also handles the main edge cases (private companies, empty FDA results, expired USPTO API) and both input parameters thoroughly. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is already 100%, but the description adds real semantic value: it clarifies that 'type' accepts 'company' or 'ticker' interchangeably, enumerates the three accepted value shapes (ticker, zero-padded CIK, company name), and gives concrete examples like 'AAPL', '0000320193', and 'Moderna'. It also explains the name-resolution fallback via SEC EDGAR.

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 names a specific verb (profile/research/brief) and resource (US public company) with multiple natural-language examples, and clearly states it fans out across SEC, XBRL, patents, contracts, FDA, hiring, news, and GLEIF in one call. It differentiates itself from single-pack lookups and sibling alternatives like compare_entities by focusing on a holistic, per-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 explicitly says 'ALWAYS PREFER' this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, and explains when a private company yields resolved:false. It does not explicitly exclude use cases like direct comparison or deep research, but the primary when-to-use guidance is unambiguous.

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

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

Annotations already 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?

Even with readOnlyHint/openWorldHint/idempotentHint covering safety, the description adds substantial operational behavior beyond annotations. It explains matcher behavior, compatibility codes, null semantics for temporal_alignment, gross-vs-net fee treatment, and skipped leg counters. It also flags that compatibility fields can be non-empty even when matched_pairs>0, preventing a dangerous misinterpretation.

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 organized with labeled sections (modes, response, safety fields, codes, fees) and front-loads the core purpose and the two modes. It could be tightened slightly because null semantics and compatibility codes are described twice, but no sentence is pure 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?

With no output schema, the description carries full responsibility for return semantics, and it delivers: leg-by-leg prices, top_spreads_pp, compatibility_warning/codes, per-spread flags, temporal_alignment, fees_note, and skipped counters are all explained. It also covers the main edge case an agent would encounter—pre-mapped topics are often not currently tradeable.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining that explicit tickers override the topic-mapped side and that both modes run the identical token-overlap matcher. This clarifies interactions between the otherwise independently documented parameters.

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

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

The description opens by defining the tool as a 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which names the exact resource and scope. It then enumerates two concrete modes and the response shape, making it easy to distinguish from Polymarket-only sibling tools.

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

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

The description gives clear context for both modes: use topic shortcuts for pre-mapped macros and explicit Kalshi/Polymarket identifiers for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility warnings. However, it never explicitly names alternative sibling tools or states when to use them instead.

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

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

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. It explains the cross-source identity spine (CIK, ticker, LEI, FIGI), graceful degradation when GLEIF/OpenFIGI are unavailable, ambiguous-match behavior returning figi_candidates instead of asserting a wrong answer, explicit unresolved identifiers, and the fact that each call cascades through multiple internal endpoints. This far exceeds the safety hints already provided by readOnlyHint, openWorldHint, idempotentHint, and destructiveHint.

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 and dense, but almost every sentence carries useful operational detail, including edge cases, fallback behavior, and source attribution. It is front-loaded with examples and the 'Use FIRST' instruction, then organizes supported types with sub-details. Some redundancy and parenthetical density exists, but given the complexity of the tool, the length is largely justified. It is not as lean as it could be, but it is far from bloated.

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

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

Given the tool's complexity, the absence of an output schema, and the two-parameter schema, the description is remarkably complete. It explains return behavior implicitly by describing figi_candidates for ambiguous matches, the unresolved list, source-labelled identifiers, and fallback behavior when upstream services fail. It even tells the agent what kind of input to pass (entity name only) and why. No critical operational aspect appears missing for an agent to correctly select and invoke this tool.

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

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

Although the schema already covers both parameters 100%, the description adds substantial meaning beyond the schema. It explains what values mean in practice for each type (e.g., ticker vs. CIK vs. name for company; brand vs. generic for drug), gives concrete examples, explains the bond issuer-name matching caveat, and clarifies the behavior when multiple instruments match. This is a case where the description elevates the parameter semantics well above the schema 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 states a specific, actionable purpose: resolving a user-spoken NAME to canonical/official identifiers that other tools require as input. It goes further with concrete examples ('ticker for…', 'CIK for…', 'LEI for…') and explicitly distinguishes the two supported entity types, company and drug, making it clear what the tool does and how it differs from ordinary search. The phrase 'Use FIRST whenever you have a name but need an ID' solidifies its role among sibling tools.

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

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

Strong usage guidance is present: 'Use FIRST whenever you have a name but need an ID' gives an explicit trigger condition. The description also provides detailed input-format guidance, including what to pass for bonds and what not to pass ('never the question's full noun phrase'). However, it does not name specific sibling alternatives or explicitly state when NOT to use this tool, so it falls just short of a 5.

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

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

Annotations already 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.