Hts

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: the default model (Workers AI Llama-3.3-70b, free), the BYO-key billing model for Anthropic (charged directly), and the per-model return structure. It does not cover rate limits or failure modes, so not a 5.

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 tightly written sentences: purpose, model/billing, return format, and use cases. No filler; all information is relevant and front-loaded with the main action.

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

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

Despite no output schema, the description covers the result shape (per-model score/confidence/signals/raw_response + combined view). It also addresses defaults, auth/billing, and example use cases. For a read-only probing tool, this 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: 'models' omitted means workers-ai, '_apiKey' is for Anthropic and passed straight through, and 'context' helps disambiguate common names. This elevates it above the 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 opens with a specific verb+resource: 'Probe one or more LLMs for what they know' and clearly states the output is a visibility score (0-100). This differentiates it from sibling tools like ask_pipeworx (chat/QA) and scan_competitor_ai_presence (which likely focuses on competitor presence rather than general entity visibility).

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. optional Anthropic model. However, it does not mention when not to use this tool or explicitly name alternatives, so it misses the 'exclusions' criterion for 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is well-covered. The description adds beyond annotations by explaining the routing behavior (to 5,578 tools), the return format (structured answer with citation URIs), and its role as a default entry point. It does not mention potential latency or cost, but these are not required given the strong annotation coverage.

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

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

The description is dense but highly efficient. It leads with the most critical instruction ('PREFER OVER WEB SEARCH'), then lists covered domains, explains the routing mechanism, gives examples, and contrasts with siblings—all in a few sentences. No filler; every sentence contributes to proper tool selection and use.

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 explaining what the return value looks like (structured answer with citations). It also covers a wide range of use cases, mentions limitations (when to step up to other tools), and provides enough context for an agent to decide confidently. With 34 siblings, the description successfully carves out a unique role.

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

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

Schema coverage is 100% with all six parameters described (question and five aliases). The description reinforces the parameter semantics by providing examples of valid queries and clarifying that the 'question' field accepts natural language. It adds value beyond the schema by illustrating the type of input expected, though the schema already covers the technical 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 clearly states the tool's purpose: to answer factual questions about real-world data by routing to thousands of sources and returning structured answers with citations. It names specific domains (SEC, FDA, FRED, patents, etc.) and explicitly contrasts with sibling tools like ask_pipeworx_grounded and deep_research, making it easy to distinguish.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE', and 'Step up only when needed' with clear descriptions of when to use alternatives (grounded for verbatim evidence, deep_research for broad/multi-part queries). Also gives concrete examples of appropriate questions, making the decision process very 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, non-destructive), the description discloses that it is an experimental edge with candidate routing improvements that may be enabled live, and that currently no candidate is active. This adds valuable context about potential variability and its beta nature without contradicting annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value (beta status, current equivalence, usage guidance, and reassurance that it's fully functional). No wasted words.

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

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

Given the tool's complexity as a router, the description adequately covers its relationship to the stable version, its experimental nature, and its functionality. It mentions the same response shape, which is sufficient despite no output schema. Minor gap: doesn't specify error behavior or limitations, but not critical for a router already described elsewhere.

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

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

Schema has 100% coverage with all parameters described as aliases for 'question', which is fully explained. The description adds no extra parameter context, so a baseline of 3 is appropriate.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with 5,578 tools and the same arguments and response shape. It distinguishes itself from the stable sibling by highlighting its experimental routing improvements and current exact match to ask_pipeworx.

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

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

Explicitly tells when to use it: 'when you want the newest routing' and implies using the stable router otherwise. Also states it is a full working router, not a fallback, and gives context on how results are compared for merges.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by detailing the exact return contract: 'Returns {answer, evidence (verbatim quote), confidence, source, fetched_at, refusal_reason:null} on success' and enumerates all refusal_reason values. It also discloses the extra LLM call cost and the fact that it uses ONLY the tool result. 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 dense but every sentence earns its place. It is front-loaded with the most important distinction ('Hallucination-resistant'), then flows logically through mechanism, return value, use cases, and cost trade-off. The JSON-like output contract is efficiently embedded 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 having no output schema, the description fully specifies return values and refusal reasons, making the behavioral contract unambiguous. It also provides routing context ('5,578 across 1463 sources') and explicit alternatives. This is complete for a tool of this complexity.

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

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

Schema coverage is 100% — all six parameters are aliases for 'question' with descriptions. The description does not add parameter-level detail, but none is needed since the schema fully documents the natural-language question input. 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' — a specific verb-noun combination that clearly distinguishes it from the sibling ask_pipeworx. It explains the grounding mechanism (extracts only from tool result) and the structured refusal behavior, making the tool's purpose unmistakable.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides a clear trade-off and alternative: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is exemplary 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description goes far beyond annotations by detailing the resolution contract, exclusive statuses (low_confidence_match, market_closed_or_inactive), wide-spread illiquidity warnings, and resolution-rule risk (e.g., refund_50_50). This gives agents actionable awareness of edge cases 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 long but well-structured with capitalized section headings (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. Each section adds novel information, yet some content (e.g., detailed fan-out examples) could be trimmed without losing core guidance. Still, the structure makes it navigable for complex functionality.

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

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

For a tool with no output schema and complex behavior, the description is exceptionally complete. It explains response shapes, resolver confidence, parent event extraction, news fallback fields, safety short-circuiting, and resolution-rule risk. No critical usage detail appears missing for an agent to select and invoke the tool correctly across 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'market' parameter's accepted formats (slug, URL, question text) and adds fan-out examples that indirectly illustrate depth behavior. However, it does not materially extend the schema's parameter descriptions; the schema itself is already comprehensive.

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 a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It further distinguishes itself from siblings by focusing on individual bet research rather than broad edge scanning or arbitrage, and explicitly names use cases ('should I bet on X'). This is unambiguous and differentiates from sibling tools.

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

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

The description provides explicit when-to-use context: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not explicitly name alternatives or state when not to use the tool in favor of siblings like polymarket_edges. It still gives clear context and practical guidance on matching resolution confidence.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses data sources (SEC EDGAR/XBRL), fiscal year handling, metric types per entity, sorting by primary metric, and output format (paired data + pipeworx:// citation URIs). There is no contradiction with annotations.

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

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

The description is front-loaded with trigger phrases and the core action. Every subsequent sentence adds operational value (metrics, sorting, output, call efficiency) without redundancy. While long, it is justified by the tool's complexity and remains well-structured.

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

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

With no output schema, the description adequately explains return values: paired data and citation URIs. It also covers data sources, sorting, entity count limits, and the parallel-call optimization, 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?

Although schema coverage is 100%, the description adds meaningful semantics: for type='company' it specifies exact financial metrics (10-K revenue, net income, cash, LT debt) and fiscal-year handling; for type='drug' it lists FAERS counts, FDA approvals, trials. This goes beyond the schema's enum descriptions, aiding correct parameter selection.

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: side-by-side comparison of 2–5 companies or drugs in one parallel call. It uses specific verbs ('compare', 'rank', 'head to head') and explicitly distinguishes from sequential single-pack lookups, which separates it from siblings like entity_profile.

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

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

Usage guidance is explicit: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It enumerates trigger phrases (e.g., 'which is bigger') and states it replaces 8–15 sequential lookups, giving clear direction on when to select this tool over alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses auth and paid-tier requirements, latency expectations, gap recovery and contradiction scanning, semantic excerpting behavior, and citation fetchability. It also explicitly says findings are never invented and includes gaps[], which goes well beyond what annotations alone 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 dense and front-loaded with the account requirement and the key distinction from ask_pipeworx. Every clause carries useful information, but the single long paragraph with many semicolon-separated asides is harder to scan than a structured list would be.

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 having no output schema, the description fully covers the expected return structure (evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop), auth prerequisites, latency, and when results will be empty. This is sufficient for an agent to invoke the tool 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 description coverage is 100% and both parameters are documented there, so the baseline is 3. The description adds meaningful extra semantics for depth (quick vs standard gap recovery vs thorough iterative hop and paid requirement) and clarifies that broad natural-language questions are expected, justifying 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 specifies a clear action: grounded multi-source research across Pipeworx's 1463 structured data sources, decomposing questions into facets and routing them in parallel. It also distinguishes the tool from ask_pipeworx and from open-web search, making its purpose unambiguous relative to 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 explicitly states when to use deep_research (broad/multi-part structured-data questions) and when to prefer ask_pipeworx (single lookup, breaking/current-news topics, or when not signed in). It names alternatives directly and explains depth-tier behaviors, so an agent can confidently choose among siblings.

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

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

The description discloses the return behavior in detail: returns top-N most relevant tools with names, descriptions, and full input schemas including curated examples, ready to call directly with no second schema lookup. It also states the 'call this FIRST' ordering. Annotations already declare read-only and idempotent, and the description adds meaningful behavioral context beyond that.

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 ('Find tools'), then provides a useful domain list, return format, and a usage directive. Every sentence earns its place, and the structure flows logically from what to when to return 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 discovery tool, the description covers purpose, usage, return format, and direct invocation readiness. It is self-sufficient even without an output schema, and the read-only annotations align with the described behavior. No gaps remain.

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

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

Schema description coverage is 100%: the query parameter is fully documented with aliases and examples, and limit is explained. The description only loosely references 'describing the data or task' without adding new parameter-level semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Find tools by describing the data or task.' It enumerates the domains covered (SEC filings, financials, FDA drugs, etc.), making the tool's purpose unmistakable. It clearly distinguishes itself from sibling data tools by being the meta-tool for 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?

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and advises calling it FIRST when many tools are available. It offers clear context but does not explicitly exclude scenarios or name alternative tools, so it stops just short of a perfect score.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds substantial context: fan-out across five specific sources, soft-fail on USPTO patents due to API sunset, GDELT→GNews fallback, and detailed return fields including sorted fundamentals and filing URIs. 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 a long paragraph, but every sentence carries useful information: trigger phrases, usage preference, fan-out sources, returns, and constraints. It could be bulleted for scanability, but the density is appropriate for the tool's complexity and it front-loads the most important trigger examples.

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 fully explains return values: cik, company_name, recent_filings with URIs, fundamentals with specific fields and ordering, patents soft-fail, news fallback, and LEI. It also mentions input constraints and sibling guidance, making it complete for a complex multi-source tool.

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

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

Schema description coverage is 100% for both parameters, so baseline is 3. The description repeats the same ticker/CIK format and names-not-supported note, adding examples but no new semantics. It does not meaningfully go beyond what the schema already provides.

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

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

Description states a specific action: producing a full cross-source profile of a US public company in one call, with clear example queries. It distinguishes from siblings by explicitly saying names are not supported and to use resolve_entity first, and differentiates from single-pack lookups by promoting a holistic view.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a clear alternative: 'use resolve_entity first if you only have a name.' This directly tells the agent when to use this tool vs alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context about clearing sensitive data and that the memory was previously stored, going slightly 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 two sentences, front-loaded with the action, then covers usage guidance and related tools. Every sentence earns its place with no fluff.

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

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

The tool is simple (one param, no output schema), and the description plus annotations cover purpose, usage, and safety profile completely. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the single 'key' parameter is fully described in the schema. The description adds no new parameter-specific details, so it meets the 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, which is a specific verb+resource. It distinguishes itself from sibling tools like remember and recall by focusing on deletion.

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 provides when to use the tool ('when context is stale, the task is done, or you want to clear sensitive data') and mentions pairing with remember and recall, effectively guiding tool selection.

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

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

Annotations already declare readOnly/idempotent/destructive false. The description adds valuable process context (fetches page, extracts title/description/key links, emits standard markdown) and output format (single text blob). No contradiction; adds beyond annotations.

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

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

Three sentences, each with a distinct purpose: primary function, process/output, and use cases. Front-loaded with the main action and benefit, 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 2-param tool with full schema coverage and annotations, the description fully explains the output (a single text blob) and typical use cases. No output schema exists, so the description adequately covers return value.

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 both 'url' and 'max_links' are already fully documented. The description does not add additional parameter-level semantics beyond the schema, earning the baseline score.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, with a specific verb (Generate) and resource (llms.txt). It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation, not just scanning.

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

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

Explicitly lists use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'). It lacks explicit when-not or alternative tool names, but provides clear context for when to use.

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

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

The description goes well beyond the readOnlyHint and idempotentHint annotations by explaining what the tool computes: resolving Section 301/232 Chapter-99 add-ons into an effective total, and returning base rates, Chapter-99 provisions, and a plain-language note. It does not mention limitations or edge cases, but annotations already confirm a safe, non-destructive operation, so the extra context is sufficient.

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

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

The description is front-loaded with the core action and uses three sentences, each contributing useful information: the function, the usage context with a concrete example, and the return payload. It is slightly long due to the tariff calculation example, but nothing is wasted, and the structure makes the complex behavior clear.

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

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

The tool has no output schema, so the description correctly takes on the burden of explaining return values: base rates, Chapter-99 provisions, and a plain-language note. It also covers when to use it, a concrete example, and how it differs from the sibling search tool, 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?

The input schema already provides a 100% description of the hts_code parameter with examples, so the description only adds the 'ONE' qualifier and an illustrative tariff example. This is helpful but does not meaningfully expand parameter semantics beyond the schema's own coverage; a 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 uses a specific verb ('Get'), names the resource ('full tariff detail for ONE HTS code'), and explicitly distinguishes itself from the sibling tool hts_search by focusing on post-search detailed lookup. The scope (ONE code), the added Chapter-99 resolution, and the example make the tool's purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use after hts_search when you have the specific code and need the REAL landed tariff.' It also names the alternative workflow ('after hts_search') and gives a concrete example, so an agent knows the correct invocation context and what to expect.

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. The description adds behavioral context by listing the returned fields (general, special, column-2 rates, units, Section 301/232 footnotes) and disclosing the limitation that effective totals require hts_lookup, exceeding what annotations alone provide.

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

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

The description is four sentences, each earning its place: purpose, usage guidance, input format, and output/limitation. It is front-loaded with the core action and avoids redundancy, making it concise 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?

Despite having no output schema, the description fully explains what is returned (matching tariff lines with specific rates and footnotes) and covers input types and the key limitation. With rich annotations, this is a complete introduction to 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 schema covers both parameters with 100% description coverage: query and limit are fully described. The description's input examples ('bicycles', 'lithium batteries') echo the schema and don't add new meaning beyond what the schema already provides, so a 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 uses the specific verb 'Look up' and identifies the resource as 'US import TARIFF / customs DUTY rates from the official USITC Harmonized Tariff Schedule.' It also differentiates from the sibling hts_lookup by noting the latter provides 'EFFECTIVE total including those add-ons,' making the purpose and scope 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?

It explicitly instructs to 'PREFER OVER WEB SEARCH' for tariff queries, listing example query types. It also says 'For the EFFECTIVE total including those add-ons, pass the exact code to hts_lookup,' providing direct guidance on when to use an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by specifying the return fields (id, type, params, created_at, etc.) and confirming it only shows the caller's own subscriptions, going beyond annotation coverage.

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

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

The description is concise and well-structured: one sentence states what it does and what it returns, the second gives practical usage guidance. Every word adds value, with no fluff or repetition.

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

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

For a simple read-only list tool with one optional parameter, the description is complete. It explains the result fields, scope (caller's own), and provides actionable use cases. The rich annotations and full schema coverage mean no critical information is missing.

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

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

The input schema fully documents the single optional parameter include_inactive with a clear description. The tool description does not add any parameter-specific semantics, so with 100% schema coverage a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also distinguishes from siblings like subscribe/unsubscribe by focusing on review and lookup, making its purpose unambiguous.

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

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

The description provides explicit usage context: use it to review current monitoring before adding more, or to find an id to cancel. It does not explicitly name alternatives but clearly implies when this tool is appropriate relative to subscribe/unsubscribe, so it earns a 4.

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

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

The description discloses several behavioral traits beyond the annotations: rate-limited to 5 per identifier per day, free and doesn't count against quota, claim_token behavior for tracking, and team's daily digest review. The annotations provide minimal hints (all false), so the description carries the full burden and does so thoroughly without contradicting any annotation.

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

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

The description is dense and covers many necessary details (usage, exclusions, token flow, rate limits, quota, team behavior). While longer than a typical tool description, every sentence serves a distinct purpose and there is no fluff. Information is front-loaded with the main action and use cases.

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

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

Despite no output schema, the description explains what the tool returns: a claim_token when filing without an account, and status/resolution details when the token is passed later. It also covers constraints (rate limit, quota) and context for what to include in the message. For a feedback tool with 4 parameters, this is complete and self-contained.

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. The description adds meaningful extra context for claim_token ('pass the pwfb_… token that filing returned, with no other arguments') and explains the return behavior when filing without an account. It also elaborates on the 'type' parameter's purpose. This goes 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates the feedback types (bug, feature/data_gap, praise) and distinguishes this tool from all sibling tools, which are research, visibility, or subscription tools. There is no ambiguity about what this tool does.

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 when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also states a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and directs users to file with the other server otherwise. This is exemplary usage 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 cover read-only/idempotent safety. The description adds valuable context: self-aggregating signal, no PII, derived from CF analytics-engine, and cache timing. This goes beyond the annotations and gives a clear behavioral contract.

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

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

Well-structured and front-loaded. The first sentence states purpose, the second lists outputs, the third lists use cases with numbering, and the final sentence covers data provenance and caching. Every sentence carries useful information without waste.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description is complete: it explains what is returned, when to use it, performance characteristics (caching), and privacy implications. No significant gaps.

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

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

Schema coverage is 100% and the schema includes a full description of the window parameter, including the semantics of shorter vs longer windows. The tool description merely mentions 'recent window' without adding new parameter-level detail, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it returns trending tools, top packs, and total call volume from other AI agents' Pipeworx usage. It distinguishes itself from siblings like discover_tools by focusing on popularity signals rather than general 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?

Provides three explicit use cases: uncovering hot data sources, confirming canonical tool choice, and aligning with agent demand. Does not name alternatives or exclusions, but the context is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond these: it explains the partition filter (drops placeholder slugs), the fill check (realizable_edge_pp ≤ 0 means do not trade), and how skipped_low_similarity surfaces rejection counts. 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 it is well-structured with clear sections (modes, semantic anchor, partition filter, response, fill check). It front-loads the core purpose and usage modes. Every sentence adds necessary detail for a complex arbitrage tool, so it earns its place, though it is denser than the minimal two-sentence ideal.

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 having no output schema, the description explicitly lists the response fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check details). It covers all modes, edge cases (placeholder filtering, low similarity), and operational caveats (fill check, realizable edge). This makes the tool fully self-contained for an agent.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic', but the tool description goes further by detailing exactly what happens with each parameter: event mode walks child markets and computes partition_check, topic mode searches related events and flattens markets. It also clarifies accepted formats (full Polymarket URLs) and gives example slugs, adding 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 opens with a specific verb+resource+approach: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings by detailing three modes (trending_scan, event, topic) and references to other Polymarket tools like polymarket_fill_risk.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also contrasts modes ('Cross-event mode catches ... that single-event misses') and directs users to 'polymarket_fill_risk' for custom sizing, providing clear when-to-use and 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?

The description provides extensive behavioral detail far beyond the annotations: it explains the internal model families, the placeholder-slug filter, the 24h-move warning, the Kelly capping, cache behavior, and the diagnostics for empty segments. It also clarifies why Fed bets are unreliable. This is a highly transparent disclosure of the tool's inner workings and limitations.

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

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

The description is long but well-organized with uppercase section headers, numbered model families, and explicit response top-level fields. The first sentence is a concise TL;DR. Some details (e.g., specific alpha values) are dense, but they are relevant and earn their place. It is structured clearly enough for an agent to navigate.

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

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

Despite lacking an output schema, the description fully explains the response structure: by_segment with three segments, fed_candidates/fed_note, and _diagnostics with funnel counters. It also enumerates the key fields carried per opportunity (edge_pp_net, kelly_fraction, market.liquidity, etc.). For a tool with 9 parameters and complex internal logic, the description is remarkably complete.

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

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

While the schema covers 100% of parameters, the description adds substantial semantics: it explains the interaction between min_kelly and min_partition_leg_kelly ('Partition arbs always return kelly_fraction_half=0 at the parent level'), gives real-world context for slippage_pp (zero fees but 20-50bp typical), and defines the tradeable-edge filters. This goes well beyond the schema's own descriptions.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes its purpose from siblings like polymarket_arbitrage by focusing on cross-model disagreement and daily discovery ('what should I bet on today'), and it names the distinct model families and segments it returns.

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: built for daily opportunity discovery without paging hundreds of markets. It also describes usage of knobs and explains exclusions (e.g., Fed bets excluded due to unreliable signal). However, it does not explicitly mention alternatives or say when NOT to use this tool versus sibling tools, which prevents 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?

The description adds substantial behavioral context beyond the readOnlyHint and destructiveHint annotations. It discloses that history depth is bounded by a 60-day TTL, that snapshot gaps occur due to cache-misses, and that decay numbers come from daily closes net of default slippage. These are non-obvious traits that help the agent anticipate limitations and interpret results.

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

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

The description is long but every sentence carries essential information. It front-loads the core purpose, then logically covers arguments, response structure, and limitations. There is no fluff or repetition; the density is justified by the tool's complexity and the absence of an output schema.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains the full response anatomy: tracked[] with time-series fields, expired[] with lifespan comparisons, and snapshot_dates[] with gap semantics. It also covers edge cases like TTL limits and non-intraday data, leaving little ambiguity for the agent.

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

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

Schema coverage is 100%, and the schema already describes defaults and clamping for both parameters. The description adds semantic meaning by explaining 'window' as a 'snapshot family' with the default '1wk', and clarifies that 'days' controls the lookback depth. This goes slightly beyond the schema, justifying a score above the baseline 3.

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

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

The description clearly states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a strong verb and resource, and directly distinguishes itself by answering 'how long has this edge existed and is it shrinking?' This differentiates it from sibling tools like polymarket_edges (current snapshots) and polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool: when assessing whether an edge is fresh or old, noting that 'a fresh wide edge and a 3-week-old wide edge are different trades.' It effectively implies the tool is for historical persistence analysis. However, it does not explicitly name alternative tools or state when not to use it, so it falls 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?

Beyond annotations (readOnlyHint, idempotentHint), the description details behavior: 'walks the ladder', returns specific fields (top_of_book, slippage_pp, verdict), and explains the risk of partial fills converting arbs into unhedged positions. It clarifies parameter interpretation (size_usd as target proceeds or settlement notional) and output semantics without contradicting annotations.

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

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

The description is long but well-structured with SINGLE-MARKET and BASKET sections, and the core purpose is front-loaded. Every sentence contributes information, though some length could be trimmed. Structure aids navigation, but it's dense.

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 carries the burden of explaining return values. It lists all key outputs for both modes (top_of_book, slippage_pp, capture_ratio, thin_legs, forced_directional_risk) and adds usage constraints (size clamp, required one of market/event). It's fully sufficient for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds mode-dependent meaning: it clarifies that exactly one of market/event is required (schema has 0 required), explains side auto-detection in basket mode, and differentiates size_usd interpretation between buys/sells and single/basket modes. This goes beyond schema descriptions.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly identifies the tool's function and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by positioning it as a pre-trade risk check.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the two modes (single-market vs basket) with conditions and warns about the dominant loss mode, providing clear alternatives context.

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

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

Extensive disclosure of behavioral safety mechanisms: compatibility_warning cases, temporal_alignment, skipped_cross_type/subtype counters. Annotations already declare read-only; description adds rich detail on edge cases and output semantics. No contradiction.

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

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

Long but well-structured with labeled sections. Each sentence provides substantive detail; no fluff. Front-loaded with core purpose.

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

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

No output schema, so description carries burden of response explanation. Covers leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skipped counters. Thorough for a complex tool.

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

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

Schema covers all 3 params (100%). Description adds mode grouping and auto-fetch vs custom pairing context, but little new per-parameter semantics beyond schema.

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

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

States specific purpose: compute cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinct from siblings like polymarket_arbitrage. No ambiguity.

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

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

Explains two modes (topic vs explicit tickers) and warns that pre-mapped ≠ tradeable. Provides context on when the tool is applicable (same resolving question) but does not explicitly name alternatives or when not to use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safe read behavior is known. The description adds valuable context: it differentiates between retrieving a value and listing keys, explains the scoping mechanism ('Scoped to your identifier'), and notes the optional key behavior. It does not disclose what happens if a key is missing, but this is a minor omission given the simplicity and annotation coverage.

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

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

The description is two sentences, front-loaded with the core action, then expanded with usage context, scoping, and related tools. Every sentence earns its place without redundancy or tangential information. It is both concise and structurally effective.

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

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

For a tool with a single optional parameter and no output schema, the description covers all essential aspects: purpose, usage context, behavioral nuances (key omission), scoping, and relationships to sibling tools. It is complete enough for an agent to correctly select and invoke the tool in a variety of scenarios.

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

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

The schema already provides 100% coverage with a clear description for the 'key' parameter. The description adds semantic meaning by explaining that omitting the key lists all keys, which is not fully captured in the schema's static description. The examples further reinforce this, giving the agent a practical understanding of both invocation modes.

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 with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and explicitly contrasts with 'list all saved keys' when the key is omitted. It distinguishes itself from sibling tools 'remember' and 'forget' by framing its role in the trio, making its purpose unambiguous.

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

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

The description gives concrete guidance on when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also explicitly pairs with 'remember to save, forget to delete,' providing clear alternatives and usage context. This goes beyond a simple action statement and offers practical invocation 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 states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a side-effecting state change. This directly contradicts the annotation readOnlyHint:true. Flagged as 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?

Three sentences, each earning its place: the first states purpose and return fields, the second explains filters and mark_read behavior, the third addresses polling and an external alternative. 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?

With no output schema, the description adequately covers return fields and filtering. It doesn't mention default limit or unread_only, but those are in the schema. The annotation contradiction about read-only behavior creates some confusion, but overall the tool is well described for a read-oriented operation.

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, but the description adds valuable semantics beyond field names: a concrete type example ('sec_8k'), the effect of mark_read on future calls, and clarification that since uses an ISO timestamp. This goes beyond the schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' which is a specific verb+resource formulation. It further details return contents (source, citation_uri, raw event payload) and filters, clearly distinguishing it from siblings like list_subscriptions or recent_changes.

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

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

Provides clear context: polling works fine and an alternative HTTP endpoint (GET registry.pipeworx.io/alerts.json) is available for scripts/dashboards. However, it does not explicitly state when not to use this tool or name a sibling alternative.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description doesn't need to repeat safety profile. It adds valuable behavioral detail beyond annotations: fan-out to multiple sources in a single call, GDELT→GNews fallback on rate limits/5xx, USPTO soft-failure due to PatentsView API sunset, and `since` format details. These disclosures help the agent anticipate side effects and edge cases.

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 contributes meaning: from usage examples to source details, parameter guidance, return shape, and an alternative. It is front-loaded with the core purpose and structured logically. Slightly verbose due to the enumeration of sources and fallback logic, but nothing is 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?

Given the tool's complexity (multi-source fan-out, fallbacks, soft-fail) and lack of an output schema, the description fully covers what is returned: structured changes[] grouped by source, total_changes count, and pipeworx:// citation URIs. It also addresses the entity_profile alternative, making the tool self-contained for an agent to decide 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%, so the baseline is 3. The description adds extra semantics by giving concrete relative shorthand examples for `since` ('7d', '30d', '3m', '1y') and a recommendation to use '30d' or '1m' for typical monitoring, which goes beyond the schema's generic description. It also clarifies the `value` parameter implicitly through the entity_profile contrast (ticker/CIK), though the schema already covers 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 opens with concrete natural-language queries and then states the core function: a change feed for a company over a time window, in one parallel call. It distinguishes itself from the sibling `entity_profile` by explicitly contrasting dynamic changes with a static profile, making the tool's purpose unmistakable.

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

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

The description provides explicit context for when to use the tool (e.g., 'What's new with X', 'latest on Y') and gives a clear alternative: 'Use entity_profile instead when you want the static profile'. This satisfies the when/alternative criteria, and the fallback behavior (GDELT→GNews) further clarifies operational expectations.

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

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

The description adds valuable behavioral context beyond annotations: it explains scoping ('scoped by your identifier') and persistence semantics ('persistent memory' vs 'anonymous sessions retain memory for 24 hours'). These details are not covered by idempotentHint or destructiveHint and meaningfully inform the agent about side effects and storage duration.

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 earning its place: action, usage context, and persistence details. It is front-loaded with the core purpose and avoids redundant phrasing, making it concise 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 simple 2-parameter tool with no output schema, the description is complete. It covers purpose, usage, persistence, scoping, and complementary tools. Annotations already provide idempotence/destruction hints. No additional behavioral information is needed for an agent to use 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?

Schema description coverage is 100% for both key and value parameters, so the schema fully documents them. The tool description mentions key-value pairs and gives examples of stored content ('resolved ticker, target address'), but this is illustrative rather than adding new syntax or format details. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' – a specific verb ('save') and resource ('data'). It distinguishes itself from siblings by explicitly mentioning 'recall' for retrieval and 'forget' for deletion, making the purpose unique among similar memory 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 clear when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names complementary tools (recall, forget). However, it doesn't explicitly state when not to use it, though the phrase 'worth carrying forward' implies the condition.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds rich context: the tool cascades through multiple lookup endpoints internally, degrades gracefully (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), labels every identifier with its source, and explicitly lists unresolved identifiers. It also mentions that an ISIN resolves to the legal entity via GLEIF mapping. 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 relatively long but well-structured: examples first, then purpose, then detailed type breakdowns, then degradation note, then benefit. Every sentence adds value, and the most critical information ('resolve a name to an ID') appears early. Could be slightly condensed by merging some type details, but overall efficient for the complexity of the tool.

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

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

Given the tool's complexity (2 parameters, no output schema), the description is remarkably complete. It defines input forms, explains return structure (labelled identifiers, unresolved field), covers edge cases (graceful degradation), and notes internal cascading behavior. An agent would have sufficient information to use and interpret results without additional 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 parameters described in schema). The description adds value by elaborating on the 'value' parameter with concrete examples (ticker 'AAPL', CIK '0000320193', ISIN like 'CH0038863350', drug names) and explaining input formats. It also clarifies how the 'type' enum relates to the rich resolution logic. This goes beyond the schema's basic descriptions, providing situational examples and behavioral context.

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

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

The description opens with concrete example queries ('What's the ticker for…'), then states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists two supported entity types with detailed explanation. This clearly distinguishes the tool from siblings (e.g., entity_profile, compare_entities) by focusing on name-to-ID conversion. The purpose is specific, actionable, and immediately understood.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' (likely meaning 'first'). It covers what input forms are accepted for each type and mentions graceful degradation. While it does not enumerate specific alternative tools or say 'do not use if you already have an identifier,' the guidance is clear enough for most cases. A direct exclusion statement would push this to 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing the safety profile. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity. It also notes the first entity is treated as the 'subject', adding narrative context beyond annotations.

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

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

Three sentences, front-loaded with the main purpose, followed by mechanism/output and a concrete use-case example. Every sentence earns its place; 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?

Despite the absence of an output schema, the description explicitly states the output format (ranked list with score, confidence, signal density), names the probe method, and provides a concrete use case. Combined with the rich schema and annotations, an agent has sufficient 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?

Schema coverage is 100%, with all four parameters described in the input schema. The description reinforces 'your brand + N competitors' but does not add new parameter-level details beyond what the schema already provides. Baseline of 3 is appropriate per the rubric.

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 ('Compare') and resource ('AI visibility across multiple entities side-by-side'), clearly distinguishing it from single-entity tools like ai_visibility_check by explicitly naming it as the underlying probe. It also states the key output (ranked list, most/least recognized), making the tool's purpose unambiguous.

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

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

Provides a clear use case: competitive AI-marketing audits ('does Claude know about us as well as our competitors?'). It implies this tool is for multi-entity comparison vs single checks, but does not explicitly exclude alternatives or name when not to use it, so 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?

Annotations already establish read-only/idempotent behavior, and the description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will list timeouts, and the return structure is fully outlined. This goes beyond the annotations to set accurate agent expectations.

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

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

The description is dense but every sentence serves a purpose: it explains the aggregation, the return shape, ecosystem scope, and failure behavior. It is appropriately front-loaded with the core 'composite check in ONE call' concept and avoids fluff.

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

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

Despite having no output schema, the description enumerates the exact return fields, per-advisory details, links, and alternative versions. It also covers latency, partial failures, and ecosystem limitations, making the tool fully comprehensible 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?

The input schema covers both parameters with clear descriptions (package name, scoped packages accepted, version defaults to latest), giving 100% coverage. The description adds minimal extra parameter meaning, but the schema carries the load, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check that aggregates data from deps.dev and bundlephobia. It gives specific verbs ('fans out', 'returns') and concrete data sources, distinguishing it from sibling research 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?

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small"' and it clarifies ecosystem boundaries ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), effectively telling when not to use this tool and where to go 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?

Adds substantial context beyond annotations: 200K char cap with truncation and flagging, BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, and return of character offsets. Annotations only declare read-only/open-world/idempotent, so this description carries the burden and does so thoroughly.

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

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

Three sentences, each earning its place: what it does, when to use it, and how it works. Front-loaded with the core action, then usage context, then technical details. No filler or repetition.

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 compensates by specifying return values (passages with offsets and similarity scores). Covers input limits, truncation flag, retrieval algorithm, and integration with a sibling tool. Complete for a tool of this complexity.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds extra meaning: example query formats, truncation behavior for 'text', and clarifies that offsets are character-based. Slightly above baseline but not deeply per-parameter, hence 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 uses a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing searching within already-fetched text and explicitly contrasts with ask_pipeworx_grounded. The outcome (top-N passages with offsets and scores) is concrete.

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

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

Provides explicit when-to-use: 'Use when the record is too big to cram into the prompt.' Names an alternative/companion tool (ask_pipeworx_grounded) and explains the pairing workflow. Also implies when not to use (if the record fits in the prompt).

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

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

Annotations already set readOnlyHint=false and destructiveHint=false; description adds substantial behavioral context: requires OAuth (anonymous/BYO cannot persist), phone verification, 10/day SMS cap, webhook HMAC signing and one-time secret, auto-disable after 10 failing runs. This far exceeds the annotations' minimal information.

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

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

Description is a dense paragraph but front-loaded with purpose and return value. While lengthy, every sentence provides useful detail (auth, types, delivery, limits). Could be improved with bullet structure, but content justifies its length.

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

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

Without an output schema, the description explicitly covers the returned subscription id, all supported types, parameter examples, delivery channels, auth prerequisites, and behavioral limits. It's complete for a relatively complex subscription creation tool.

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

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

Schema coverage is 100% with rich descriptions embedded. The description adds interpretive meaning beyond the schema, e.g. items:['5.02'] = officer change, and clarifies optional delivery object semantics with examples. It doesn't fully replicate nested schema, but schema already carries the structure.

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

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

Description opens with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id' — a specific verb+resource+outcome. It clearly distinguishes from siblings list_subscriptions/unsubscribe by focusing on creation and provisioning of delivery channels.

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

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

Provides clear context: OAuth requirement, supported subscription types, delivery channels, and mentions pulling via recent_alerts as an alternative to the feed. However, it doesn't explicitly name list_subscriptions or unsubscribe as alternatives for managing existing subscriptions, nor state 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?

With rich annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds useful context about the output (category-bucketed example questions with tool shapes) and the dynamic source (live catalog of thousands of tools). It doesn't add unnecessary safety warnings, but it does explain what the user gets and how to call it, which goes beyond the structured annotations.

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

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

The description is longer than average but every sentence contributes distinct value: example queries, purpose, output format, parameter usage, and when-to-use guidance. It is front-loaded with relatable questions and does not waste words on fluff, though it could arguably be tightened by splitting into structured bullets.

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 lack of an output schema, the description fully explains what the tool returns (category-bucketed example questions with tool+argument shapes) and how to invoke it. Together with the comprehensive annotations (read-only, open-world, idempotent), the agent has all the context needed to select and use this tool safely and effectively.

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

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

Schema coverage is 100%, and the `topic` parameter is described with enum-like values. The description adds value by providing additional examples ('finance', 'pharma', 'betting') and clarifying that omitting the parameter yields a 'cross-category spread', which is not in the schema. This enriches the parameter understanding beyond the schema alone.

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

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

The description clearly identifies the tool as 'the onboarding entry point' that returns 'category-bucketed example questions' with 'the exact tool + argument shape'. This is a specific verb+resource description that distinguishes it from sibling tools like ask_pipeworx, which focuses on answering questions rather than suggesting 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?

It explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and even names alternative tools (ask_pipeworx, entity_profile, compare_entities) for learning how to call meta-tools. It also gives clear instructions on parameter usage, including omitting `topic` for a full spread versus passing it 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?

The annotations already include idempotentHint=true and destructiveHint=false, but the description adds valuable behavioral context: it discloses that the row is deactivated rather than deleted, and that historical events remain accessible via 'recent_alerts.' This goes beyond the annotations and explains the soft-delete behavior, which is crucial for a mutation tool.

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 compact and efficiently structured. The first sentence states the primary purpose, and the second sentence adds ownership and soft-delete context. Every sentence provides necessary information without filler, and the key details 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?

Given the tool's simplicity (one parameter, no output schema), the description covers the essential contextual aspects: what the tool does, ownership constraints, and the non-destructive behavior. It also directs users to 'recent_alerts' for historical data, which addresses a potential follow-up action. No critical details are missing.

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

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

The input schema has 100% description coverage for the single parameter 'id,' explicitly stating it is a subscription uuid returned by subscribe. The description merely refers to 'by id' without adding any new semantic information, so it does not enhance the schema's explanation. Baseline of 3 is appropriate when schema covers all 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 begins with 'Cancel a subscription by id,' which clearly states the action (cancel) and the resource (subscription), and distinctly differentiates it from sibling tools like 'subscribe' and 'list_subscriptions.' The verb is specific and the scope is 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 clear usage context by stating ownership enforcement: 'you can only cancel your own subscriptions.' It also implies that for historical events, users should use 'recent_alerts' instead, effectively giving an alternative. However, it does not explicitly state when not to use this tool or mention alternative tools for other scenarios, so it lacks full exclusion guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds significant behavioral context: it defines the verdict set, explains that 'could_not_verify' means the check did not happen and must not be treated as evidence, and clarifies 'unsupported' versus 'could_not_verify'. This goes well beyond the annotations and helps the agent reason about edge cases.

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 front-loaded with trigger phrases and packed with necessary routing and error-semantics details. Each sentence contributes, though the 'Replaces 4–6 sequential calls' note is somewhat extraneous to core usage and could be trimmed without losing essential guidance.

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

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

Despite having no output schema, the description thoroughly covers what the tool returns (verdicts, cited actual value, reasoning) and explains ambiguous outcomes like could_not_verify and unsupported. Given the tool's complexity and the two distinct routing paths, this is a complete and self-sufficient description.

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. The description adds extra meaning for tolerance_pct by explaining it overrides wording-implied tolerance and is useful for hallucination detection, and it clarifies the 'exact percent-delta math' used for financial claims. This elevates parameter understanding beyond the schema.

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

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

The description opens with natural-language triggers and a clear verb+resource statement: 'natural-language claim verification against authoritative sources.' It distinguishes itself by specifying two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for all other facts) and explicitly says it replaces 4–6 sequential calls, making its unique role obvious.

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

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

It provides an explicit usage signal: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives clear context for the two claim types (financial vs. other), but it does not explicitly name alternative tools or say when not to use it, so it falls short of a full when/when-not/alternatives articulation.

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