poetry

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the default model is free, the _apiKey for Anthropic is passed straight through and costs the user directly, and it returns a specific per-model result shape. It lacks caveats about rate limits or latency, but overall meaningful additions exist.

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 front-loaded, with four sentences that each earn their place: what the tool does, default model and pricing, return format, and use cases. There is no redundant or fluff content.

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

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

For a tool with four parameters, no output schema, and strong annotations, the description covers the essential operational details: how to invoke with defaults, the optional Anthropic path, the returned object structure, and practical application contexts. The lack of an output schema is compensated by explicitly listing the per-model fields and combined view.

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 describes all four parameters, so baseline is 3. The description enriches parameter semantics by explaining default behavior (Workers AI Llama-3.3-70b is free), the _apiKey's BYO/payment implication, and the optional 'context' role in disambiguation. This goes beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb ('Probe') and resource ('one or more LLMs') and clearly states the action: score visibility (0-100) for a business/brand/product/topic. It distinguishes itself from siblings by naming unique return structures (per-model score/confidence/signals/raw_response) and use cases like AI-marketing audits or pre-launch brand checks.

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

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

The description provides clear context on when to use the tool ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs. BYO-key model choice, which helps agents decide when to invoke it. However, it does not explicitly say when NOT to use it or name alternative sibling tools, so it stops 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?

While annotations already declare readOnly and non-destructive, description adds substantial behavioral context: auto-fills arguments, returns citation URIs, works on all tiers, is fast, and can handle news/breaking-news. No contradiction.

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

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

The description is long but well-structured and information-dense. It front-loads the most critical instruction ('Prefer over web search') and uses examples and alternative tool references efficiently, though some repetition could be trimmed.

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 output schema, the description covers return format (structured answer with citations), scope, use cases, and escalation paths. It provides enough context to invoke correctly and set expectations.

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

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

Schema already documents the question parameter and aliases with 100% coverage. Description supplements by providing a rich set of example queries showing the breadth of acceptable input, which helps agents formulate effective questions.

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

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

Clearly states it routes factual questions to 5,521 tools across 1452 sources and returns structured answers with citations. Distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs to prefer over web search, gives trigger phrases, examples, and specifies when to step up to ask_pipeworx_grounded or deep_research.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: it is a 'full working router' that 'falls back to nothing,' and its routing may differ when a candidate is under test. It also discloses the experimental nature and that results are compared against the stable router, which is beyond the annotations and critical for risk assessment.

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 moderately sized but every sentence earns its place: it establishes beta status, explains current parity, gives usage direction, and confirms robustness. It is front-loaded with 'Beta version of ask_pipeworx' and does not waste words, though it could be slightly tightened.

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 compensates by stating 'same response shape' as ask_pipeworx, which indirectly informs the agent of the return format. It provides enough context about the experimental routing, fallback behavior, and current state to understand the tool's full behavior. The lack of a detailed output description is acceptable given the reference to ask_pipeworx.

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 all six parameters are fully described in the schema itself. The description mentions 'same arguments' but adds no additional semantic detail beyond what the schema already provides. The baseline of 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router that handles the same 5,521 tools with the same arguments and response shape. It distinguishes itself from the stable ask_pipeworx by noting it is the 'experimental edge' with candidate routing improvements. This meets the 'specific verb+resource+scope' standard 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?

It explicitly instructs to 'use it exactly like ask_pipeworx when you want the newest routing' and notes it currently matches ask_pipeworx exactly, providing clear context for when to choose this beta over the stable version. It does not explicitly mention when not to use it, but the contrast with the stable router implies the alternative. This is clear enough for an agent to decide.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description discloses the exact return structure including {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and lists specific refusal reasons. It also clarifies the answer is extracted solely from tool results, preventing hallucination. 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 three dense sentences, front-loaded with the core concept. It efficiently explains mechanism, use cases, and cost tradeoff without fluff. Every sentence adds value.

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

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

Given the tool's complexity, the description fully covers return format, refusal scenarios, typical use cases, and alternative tool recommendation. It is complete enough for an agent to select and use the tool confidently, especially with rich annotations and schema.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for 'question'. The description does not add extra parameter-level detail, but since the schema fully covers aliases and semantics, 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 a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly explains the routing and extraction behavior, and explicitly differentiates from sibling ask_pipeworx by noting the same routing but grounded extraction. This is a clear, distinct purpose.

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

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

It provides explicit when-to-use guidance for high-stakes scenarios where facts must not be invented, and explicitly advises preferring ask_pipeworx for casual lookups. It also mentions the extra LLM call cost as a tradeoff, which is strong 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?

The description is exceptionally transparent about behavioral edge cases: low-confidence matches short-circuit, closed markets return a specific status, wide spreads carry tradeability flags, and resolution-rule risk is detailed. It also explains fan-out behavior and news fallback mechanisms. All of this goes far beyond what annotations (readOnly, openWorld, idempotent) 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 long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. While some examples are verbose, every section contributes behavior or edge-case knowledge. It is appropriately sized for the tool's complexity, though it could be slightly tighter.

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

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

With no output schema, the description carries full responsibility for explaining return values—and it does so extensively: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, and cancellation-rule risk. It covers safety mechanisms and failure modes, making it highly complete for an agent to understand the tool's full behavior.

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

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

The input schema already provides 100% coverage with detailed descriptions for all three parameters (market, depth, include_raw). The description reinforces but does not significantly extend this: it reiterates the market input formats and mentions depth defaults, but adds no new syntax or semantic detail 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call' — a specific verb, resource, and action. It further distinguishes itself by listing classifiers and fan-out examples, making it clear this is a comprehensive research tool for single bets, distinct from sibling tools like validate_claim or polymorphic_edges.

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

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

Explicit use cases are provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. This gives clear context for when to invoke the tool. However, it does not explicitly name alternative tools or provide when-not-to-use guidance beyond the implicit distinction from 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavior beyond that: specific data pulled (latest 10-K revenue, net income, cash, long-term debt for companies; FAERS counts for drugs), correct handling of off-calendar fiscal years, sorting by primary metric, and return format with pipeworx:// citation 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 dense and front-loaded with purpose, then adds necessary details about data sources, sorting, and output. While long, every sentence contributes meaningful information, and the structure flows logically from use case to specifics. Minor redundancy with the schema's enum descriptions but not excessive.

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

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

Given there is no output schema, the description fully covers what the agent needs to know: input formats for both entity types, data sources and metrics, sorting behavior, and return payload (paired data + URIs). It also addresses edge cases like off-calendar fiscal years, making the tool behavior predictable.

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, but the description enriches parameter meaning significantly. It explains values as tickers/CIKs for company and drug names, provides examples (["AAPL","MSFT"], ["ozempic","mounjaro"]), and notes max 5 items. This goes beyond the schema's brief descriptions, clarifying expected formats and context.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with concrete query examples. It distinguishes itself from sibling tools like entity_profile by emphasizing parallel comparison over sequential lookups and specifying the data sources (SEC EDGAR/XBRL for companies, FAERS for drugs).

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 instructs ALWAYS PREFER over sequential single-pack lookups when comparing entities, and states it replaces 8–15 sequential lookups. Also clarifies when to use type=company vs type=drug, providing clear selection criteria.

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, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial context: auth requirements ('ACCOUNT REQUIRED (free — sign in via GitHub...'), the distinction that this is 'NOT open-web search', depth-specific behaviors (gap recovery, contradictions[], citation_uri), and the explicit statement that it 'never invented' answers using gaps[]. It also discloses latency (15-60s, up to ~90s) and semantic excerpting of large records. 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 (~300 words) but dense with essential operational details: auth, alternatives, when-to-use, return packet contents, gaps[], contradictions[], latency, and semantic excerpting. It is front-loaded with the account requirement and core capability, and each sentence adds distinct guidance rather than restating annotations or schema. While it could be tightened with bullets, it earns its length given the tool's complexity.

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

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

With no output schema, the description compensates thoroughly by enumerating the findings packet fields (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), the gaps[] and contradictions[] arrays, the hop/citation_uri behavior, and the fact that large records are semantically excerpted. It also covers operational constraints like latency and auth. This is complete enough for an agent to understand what it will receive and what constraints apply.

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 context for the depth enum, explaining the facet counts ('quick=3', 'standard=5', 'thorough=8') and the paid requirement for 'thorough'. It also clarifies that the question is natural language and broad/multi-part is fine, which the schema already states but the description reinforces with examples. This extra depth-oriented detail raises the score to 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 states a specific verb ('research') and resource ('Pipeworx's 1452 STRUCTURED data sources'), clearly differentiating it from a general web search. It explicitly names siblings and explains what makes this tool unique ('Decomposes your question into focused facets, routes each to the right one of 5,521 tools IN PARALLEL'). The purpose is not a tautology—it describes the tool's decomposition and parallel-routing behavior.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names an alternative tool (ask_pipeworx) and warns about the account/paid requirement. This fully satisfies the 'explicit when/when-not/alternatives' criterion.

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

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

Annotations already cover readOnly, idempotent, and non-destructive hints. The description goes beyond by disclosing the return format (top-N tools with names, descriptions, and full input schemas with curated examples) and confirming results are ready to call directly with no second schema lookup. No contradiction.

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

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

The description is front-loaded with the core purpose, then usage, then return behavior. The domain list is long but serves to scope the tool's applicability. Each sentence has a distinct role, though the list could be considered slightly verbose.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, when to use, return content, and call-first strategy. There are no significant gaps, and it handles the missing output schema by explicitly stating what results include.

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% — every parameter, including aliases (q, task, search, description) and limits, is documented in the schema. The description adds context about the query's purpose (finding tools by task description) and the top-N behavior, but doesn't fundamentally change parameter understanding. 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 a specific verb+resource ('Find tools') and mechanism ('by describing the data or task'). It clearly differentiates from sibling tools by positioning itself as the meta-tool to browse/discover the available toolset, listing covered domains (SEC, FDA, FRED, etc.) and stating 'Call this FIRST'.

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 'Use when' condition is provided, followed by a concrete list of data/task categories (SEC filings, FDA drugs, etc.). It also gives a clear preference context: 'Call this FIRST when you have many tools available and want to see the option set', which tells the agent when to choose this over a direct tool.

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

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

The description goes well beyond the readOnlyHint and idempotentHint annotations, detailing cross-source fan-out behavior, specific return fields, fallback logic (GDELT→GNews), and the patents API sunset with soft-fail. 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 carries useful information. It is front-loaded with examples and a clear preference directive, though it could be structured with bullets for readability without losing content.

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

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

Despite having no output schema, the description enumerates the return fields (cik, recent_filings, fundamentals, patents, news, LEI) and key behavioral caveats (patents API sunset, name resolution). This is complete for a multi-source aggregation tool with only two parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a few examples ('AAPL', '0000320193') and reinforces the name restriction, but these are already present in the schema. No significant additional semantic value.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides concrete example queries and explicitly distinguishes itself from sibling tools like resolve_entity and single-pack SEC/XBRL/news lookups.

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 given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use it (names not supported) and directs to resolve_entity as 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 cover destructive and idempotent behavior, so the description adds limited extra context. It mentions clearing sensitive data, which gives a reason for use, but does not deepen the behavioral account beyond what annotations state.

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

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

Two sentences, front-loaded with the core action, followed by usage guidance. No filler or redundant content, every sentence earns its place.

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

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

For a single-parameter, no-output-schema tool with clear annotations, the description fully covers the purpose, when-to-use, and workflow context. It is complete and self-sufficient for an agent to invoke correctly.

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

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

The schema description for 'key' is complete (100% coverage), so the description adds no new parameter meaning. It merely repeats 'by key' without further detail, aligning with the baseline score of 3.

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

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

The description clearly states the action ('Delete a previously stored memory by key'), specifying the verb and resource. It distinguishes from siblings like 'remember' and 'recall' by focusing on deletion as the opposite of storing and retrieving.

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 conditions: stale context, task completion, or clearing sensitive data. It also suggests pairing with 'remember' and 'recall', giving clear guidance on the tool's role in the workflow.

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, so safety is covered. The description adds meaningful behavioral detail: it "fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format," and describes the output as a single text blob. This goes beyond annotations and helps set 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 well-structured: it opens with the primary action, then explains the process and output, and ends with concrete use cases. Every sentence adds value without unnecessary verbosity, making it efficient and front-loaded.

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

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

For a simple read-only tool with only two parameters and no output schema, the description covers the purpose, process, output format, and usage scenarios. It does not mention error handling or limitations (e.g., dynamic content), but given the low complexity and strong annotations, this is nearly complete.

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

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

Schema coverage is 100%, so both parameters (url and max_links) are already described in the schema. The description does not add per-parameter details beyond what the schema provides, though it does mention the extraction of title/description/key links which relates to the output. This is the baseline 3 for 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 is highly specific: it states the tool "Generate a production-ready llms.txt file for any URL" with a clear verb and resource. It distinguishes itself from sibling tools by focusing on llms.txt generation, and mentions the intended effect (AI crawlers can index the site cleanly).

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

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

The description provides explicit use cases: "getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor." This gives clear context on when to use it, though it does not explicitly name alternative tools or state when not to use it.

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, and non-destructive behavior. The description adds useful context by specifying the return fields and that it lists the caller's own subscriptions, which clarifies scope beyond the annotations.

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

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

Two concise sentences, front-loaded with the action and resource, and zero wasted words. Every sentence adds value, including the return fields and usage tips.

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 with one optional parameter and no output schema. The description explicitly lists return fields, which is necessary without an output schema. The usage guidance and scope make it complete for this tool's complexity.

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

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

Schema coverage is 100% for the single optional parameter include_inactive. The description does not mention it, but the schema fully documents it, so the description adds no extra parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions.' It distinguishes itself from sibling tools like subscribe/unsubscribe by focusing on reviewing existing subscriptions and finding IDs to cancel.

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: 'review what you're monitoring before adding more' and 'find an id to cancel.' It implies alternatives (subscribe, unsubscribe) but does not name them directly, 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?

The annotations (all false) provide minimal safety/side-effect signal, so the description carries the full burden. It discloses key behaviors: returns a claim_token when filing without an account, supports later status retrieval via that token, rate-limits to 5 per identifier per day, is free with no quota impact, and states that the team reads digests daily. 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 (~200 words) but every sentence serves a distinct purpose: purpose, when-to-use, exclusions, feedback formatting, token workflow, rate limits, and quota. It's slightly longer than minimal but not padded, and the first sentence front-loads the core purpose. Well-structured despite length.

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

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

Despite having no output schema, the description explains the full feedback lifecycle: filing, receiving a claim_token, and later checking resolution status. It covers exclusions, rate limits, and parameter interplay (claim_token usage). Combined with the schema's 100% parameter coverage, an agent has all necessary context to invoke the tool correctly.

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

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

Schema description coverage is 100%, and each parameter already has a detailed description in the input schema. The tool description adds workflow context for claim_token (pass it back later) and message guidance (be specific, 1-2 sentences, 2000 chars max), but these largely reinforce schema content rather than add new meaning. 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 a specific verb ('Tell the Pipeworx team something is broken, missing, or needs to exist') and resource ('Pipeworx team'), and enumerates exact feedback categories (bug, feature/data_gap, praise). It clearly differentiates itself from the sibling research and entity tools by being the dedicated feedback channel for this connection.

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 when to use the tool (for bugs, missing features, data gaps, or praise) and when NOT to use it (for tools from other MCP servers), directing users to file those elsewhere. It also provides concrete guidance on how to phrase feedback ('in terms of Pipeworx tools/packs', 'don't paste the end-user's prompt').

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

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

Beyond the readOnly/idempotent annotations, the description discloses data source (CF analytics-engine), privacy (no PII), return contents (pack, tool, count), and caching behavior (5min-1h). This adds meaningful behavioral context beyond what annotations provide.

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

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

The description is well-organized and front-loaded: a clear opening statement, output summary, use cases, and technical details. Each sentence contributes valuable information without unnecessary verbosity.

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

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

For a simple one-parameter tool with no output schema, the description covers what it returns, use cases, data origin, privacy, and caching. It provides enough context for an agent to decide when and how to invoke it.

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

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

The schema already fully documents the 'window' parameter with enum values and descriptions, achieving 100% schema_description_coverage. The tool description repeats the window values but adds no new parameter semantics, 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 function: it returns top tools, top packs, and total call volume over a recent window. It distinguishes itself from siblings like discover_tools by focusing on aggregated usage trends rather than discovery or Q&A.

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

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

The description explicitly lists three use cases ('Useful for:') covering discovery, validation, and alignment. It does not mention when not to use it or name specific alternatives, but the usage context is clear.

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

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

Beyond the read-only/idempotent annotations, the description reveals behaviors such as the 3pp partition deviation threshold, the ≥0.30 Jaccard similarity filter, and the fill-check logic against live CLOB depth. It also explains output semantics with no contradictions to 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 structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. A few internal implementation details could be trimmed, but every section adds meaningful guidance for a complex tool.

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

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

With no output schema and high tool complexity, the description covers modes, scan scope (~200 markets), response fields (opportunities[], partition_check), and risk caveats. It also explains edge cases like placeholders and thin legs, so an agent can anticipate outputs and consequences.

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

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

Although the schema already documents both params with 100% coverage, the description adds mode-specific guidance: event accepts full URLs, topic uses seed questions, and examples like 'fed-decision-may-2026' clarify expected formats. This goes well 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 and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes event, topic, and no-arg trending modes, and references the sibling polymarket_fill_risk for custom sizing, so it is not a tautology.

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

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

It gives explicit mode selection: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also directs custom sizing to polymarket_fill_risk, and warns when not to trade ('realizable_edge_pp ≤ 0 ... do not trade it'), which provides clear usage boundaries.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral context: model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), response structure with segments and diagnostics, caching behavior ('Cached 1h at the KV level'), and caveats about Fed bets being excluded from ranking. This goes far beyond what annotations provide.

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

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

The description is a dense, single-paragraph wall of text with heavy use of acronyms and technical details. While most content is valuable, the lack of line breaks or bullet points makes it harder to parse for an agent. It is not concise, but it does start with the primary purpose, providing some front-loading.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the response structure (by_segment, fed_candidates, diagnostics), why certain opportunities are excluded (Fed bets, placeholder filters), and how to interpret results (edge_pp_net, Kelly fractions, 24h-move warning). This fully prepares an agent to use the tool 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?

The schema provides 100% coverage with detailed descriptions for all 9 parameters. The description adds cross-parameter semantics, such as explaining how min_partition_leg_kelly differs from min_kelly and how tradeable-edge knobs (min_liquidity, max_spread_pp) filter opportunities. This supplements the schema without redundant repetition.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scan and return opportunities), and the use case ('what should I bet on today'), distinguishing it from sibling tools like polymarket_arbitrage by focusing on discovery across multiple model families.

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

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

The description implies when to use this tool (for discovering bet opportunities without paging hundreds of markets) and mentions 'discover opportunities' as the core scenario. However, it does not explicitly contrast with sibling tools or provide exclusion criteria (e.g., 'use this instead of X when...'), so it offers clear context but lacks explicit 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 important behavioral traits: snapshots are written on cache-miss (hence gaps in snapshot_dates), history is bounded by the 60-day TTL, decay is computed from daily closes rather than intraday, and edge_pp_net is signed by trade direction. This gives the agent a thorough understanding of data provenance 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 dense yet well-structured, moving through purpose, args, response, and limits. The analogy about fresh vs. old edges is insightful and not wasteful. Every sentence earns its place, and the use of sections (ARGS, RESPONSE, LIMITS) makes even a long description easy to scan.

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

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

With no output schema, the description fully specifies the return shape: tracked[], expired[], and snapshot_dates[], including field semantics. It also explains edge-signedness, lifespan computation, and data availability quirks. For an analytical telemetry tool, this is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline applies. The description repeats the args with defaults and adds the phrase 'snapshot family' for window, but does not add substantial new meaning beyond what the schema already provides. The response format details are useful but not directly parameter semantics.

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

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

The first sentence clearly states a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools by focusing on time-series decay rather than just current edge values.

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 establishes clear context for when to use this tool: when edge age and trend matter ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also provides behavioral constraints in LIMITS (TTL, daily closes). However, it does not explicitly name alternative tools or provide 'when-not-to-use' guidance, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint: false, so the baseline is already high. The description adds substantial behavioral context: it discloses output fields (top_of_book, vwap_fill_price, slippage_pp, verdict), warns about partial basket fills becoming unhedged directional positions, and names 'forced_directional_risk' and 'thin_legs'. This goes far beyond the annotation hints.

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

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

The description is long but densely packed with essential information. It uses structured sections (SINGLE-MARKET vs BASKET), uppercase key warnings, and front-loads the core purpose before diving into mode details. While a bit verbose, every sentence adds value for a complex two-mode tool; no filler remains.

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 must fully explain return values and behavior, and it does. It enumerates return fields for both modes, explains edge cases like thin books and partial fills, and ties usage to the broader arbitrage workflow. The description is exceptionally 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%, so the baseline is 3. The description largely paraphrases the schema's parameter descriptions (e.g., size_usd interpretation for buys vs sells, basket settlement notional) without adding significant new meaning. It does add the requirement that one of `market` or `event` must be passed, but that is a usage constraint rather than a parameter-semantics detail.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes the two modes (single-market and basket) and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges), making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (partial fills convert arb into unhedged directional position), naming the failure mode to avoid. This is a clear directive against alternative tools.

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

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

Annotations declare read-only hints, and the description goes far beyond them. It discloses compatibility_warning trigger conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the practical limitation that most pre-mapped topics currently yield warnings. This is rich behavioral context that helps set expectations.

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

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

The description is long but packed with essential details. It is logically structured with MODES, RESPONSE, SAFETY FIELDS, and a final caveat. Every sentence earns its place; for a tool with this complexity, the length is justified.

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

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

Given there is no output schema, the description thoroughly explains the key response elements: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning, and temporal_alignment. It also covers parameters fully, making the tool usable 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%, so baseline is 3. The description adds meaning by explaining the two modes and explicitly listing the 10 pre-mapped topic values, and clarifying the override behavior of kalshi_event_ticker and polymarket_event_slug. It also gives an example of an explicit ticker and slug.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes itself from intra-venue tools like polymarket_arbitrage by focusing on the Kalshi–Polymarket pair. The two-mode mechanism (topic vs explicit) is also described.

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

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

The description explains two usage modes (pre-mapped topics vs explicit tickers/slugs) and gives the caveat that 'pre-mapped ≠ tradeable' and most topics return compatibility_warning. It does not explicitly contrast with specific sibling tools, but the context signals and the mention of cross-venue vs intra-venue make the appropriate use case clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context beyond these: it is scoped to the agent's identifier (anonymous IP, BYO key hash, or account ID) and that omitting the key lists all saved keys. 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 three sentences, front-loaded with the core action. Each sentence serves a purpose: the first states what it does, the second gives use cases, the third covers scoping and sibling relationships. No redundant or filler content.

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

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

For a tool with one optional parameter and no output schema, the description is complete. It covers the operation, when to use it, scoping details, and relationship to remember/forget. The omission of return format is acceptable given the simplicity and lack of output schema.

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

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

The schema already covers the single 'key' parameter with 100% description coverage. The description adds meaning by explaining that omitting the key lists all keys and providing examples of what keys might contain (user's target ticker, address, research notes), enriching the semantics beyond the schema.

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

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

The description clearly states the tool retrieves a previously saved value or lists all saved keys when the key is omitted. It uses specific verbs ('retrieve', 'list') and names the resource (saved memory), distinguishing it from sibling tools like remember and forget.

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

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

Explicit guidance is provided: 'Use to look up context the agent stored earlier ... without re-deriving it from scratch.' It also names complementary tools (remember to save, forget to delete), giving clear context for when to use this tool relative to 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 readOnlyHint and idempotentHint, but the description adds beyond that: return format (source, citation_uri, payload), mark_read side-effect that alters read state, and polling safety. 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 compact and front-loaded with the core purpose. Every sentence adds value: return content, filtering, mark_read, polling, and alternative access. No fluff or redundancy.

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

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

Given 5 optional params, no output schema, and good annotations, the description covers return format, filtering, state change, and alternative access. It fully equips an agent to use the tool correctly without needing additional context.

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

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

Schema covers 100% of params, so baseline is 3. The description adds an example type ('sec_8k'), explains the consequence of mark_read (next call shows only newer events), and gives context for since and limit. This goes beyond the schema's descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and specifies it returns the most recent alerts. It distinguishes itself from siblings like recent_changes and list_subscriptions by focusing on subscription feed alerts with specific fields (source, citation_uri, payload).

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 usage context including filtering by type/since, mark_read behavior, and polling suitability. It also mentions an alternative endpoint for scripts, but does not explicitly contrast with sibling tools or 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds rich behavioral context beyond that: it fans out to three sources (SEC EDGAR, GDELT with GNews fallback, USPTO), notes fallback and soft-failure behaviors (GDELT preferred, GNews on rate limit/5xx; PatentsView sunset causing soft-fail), and describes the output shape (changes array grouped by source, total changes, citation URIs). This is exactly the kind of context that helps an agent predict behavior without calling the 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 dense but every sentence contributes. It opens with query examples to quickly orient the agent, then states the core function, enumerates data sources with fallback details, explains date formats, and notes output structure and an alternative tool. No wasted words, and the structure flows from purpose to usage to limitations.

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 aggregation, fallback logic, custom date parsing, structured output), the description is remarkably complete. It covers what the tool does, when to use it, how to use parameters effectively, what the output looks like, and known failure modes. Despite lacking an output schema, the description names the return fields, and annotations handle the safety profile.

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 marginal but useful meaning: it reinforces the accepted formats for `since` (ISO or relative) and provides a specific recommendation ('Use 30d or 1m for typical monitoring'), which goes beyond the schema's neutral descriptions. It also reiterates that `type` is limited to "company".

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

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

The description clearly states that this tool provides a change feed for a company (filings, news, patents) over a time window in one parallel call. It distinguishes itself from the sibling entity_profile by explicitly marking the difference: entity_profile is for the static profile regardless of window, implying this tool is for time-boxed 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?

The description opens with natural-language query examples ('What's new with X', 'latest on Y') and explicitly says to use entity_profile instead when a static profile is needed, providing a clear when-not and alternative. It also mentions typical usage ('Use 30d or 1m for typical monitoring'), giving actionable guidance.

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

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

Annotations already cover idempotency and non-destructiveness. The description adds valuable context beyond annotations: persistence behavior ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping ('scoped by your identifier'). It does not contradict any annotations.

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

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

The description is efficient and front-loaded with the core purpose. While it is five sentences long, every sentence carries meaningful information: purpose, when to use, storage model, persistence, and related tools. No fluff or redundant statements.

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 write tool with two parameters and no output schema, the description covers all relevant aspects: usage, storage format, persistence, and alternatives. It even addresses session vs. authenticated behavior, which is important context for an agent deciding whether to use it.

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

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

The schema already provides full coverage for both parameters, so the description need not repeat that. The description adds only a minor extra layer by explaining the key-value scoping and giving examples of value content, which is helpful but not critical. Baseline 3 is appropriate given the 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 and resource. It also distinguishes from siblings by mentioning 'Pair with recall to retrieve later, forget to delete,' which positions it within the memory tool family.

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

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

Explicit when-to-use guidance is provided: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Concrete examples (resolved ticker, target address, user preference) clarify the intended scenarios. It also references related tools (recall, forget) as the alternatives for retrieval and deletion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses detailed return behavior: company returns ticker, 10-digit CIK, company_name, and citation URI; drug returns RxCUI, ingredient, brand, and citation. It also notes internal cascading through multiple lookup endpoints and auto-disambiguation, providing meaningful transparency.

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 moderately long but well-structured: user-phrase examples, a directive to use first, and clear SUPPORTED TYPES sections. It is information-dense and each sentence adds value, though it could be tightened slightly.

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

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

With no output schema, the description fully explains return values for both entity types, including citation URIs. It covers input variants and disambiguation. For a two-parameter lookup tool, this is complete and self-sufficient.

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

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

Schema covers 100% of parameters, but the description adds practical examples (AAPL, 0000320193, ozempic) and clarifies auto-disambiguation behavior. It also distinguishes between company and drug value formats beyond the schema's generic descriptions.

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

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

The description clearly states the verb 'resolve' and the resource: user-spoken entity names to canonical/official identifiers. It enumerates supported types (company and drug) with specific outputs, distinguishing it from sibling tools like entity_profile or compare_entities, which analyze rather than resolve identifiers.

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

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

It gives explicit usage direction: 'Use FIRST whenever you have a name but need an ID.' It also explains that it replaces 2-3 manual lookups. It does not explicitly name when-not-to-use alternatives, but the context makes the primary use case 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?

The description discloses that it 'probes each entity with ai_visibility_check' and 'ranks by score,' providing insight into the tool's internal behavior. It also notes model constraints (workers-ai free default, anthropic requires _apiKey). The annotations already cover read-only and idempotent safety, so the bar is lower; the description adds meaningful behavioral context beyond annotations without contradiction.

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

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

The description is two sentences with an embedded example and a return-format specification. It front-loads the primary purpose and provides the key use case without extraneous text. Every sentence earns its place, and the structure makes the tool's value immediately clear.

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

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

Despite having no output schema, the description explicitly states the return format ('ranked list with score, confidence, signal density'). It covers the tool's relationship to ai_visibility_check, the competitive audit use case, and the parameter constraints (e.g., _apiKey for anthropic). The annotations and schema cover the remaining context, making the description complete for an agent to select and invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description adds little beyond the schema: it mentions 'your brand + N competitors' but the schema already details that the first entity is the subject and includes min/max counts. The models and _apiKey parameters are also fully described in the schema. The description does not materially enhance parameter understanding.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (compare), the resource (AI visibility of entities), and distinguishes itself from the sibling tool ai_visibility_check by focusing on multiple entities and ranking. It also names the exact output: 'ranked list with score, confidence, signal density per entity.'

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example query ('does Claude know about us as well as our competitors?'). It implies this tool is for multi-entity comparison, indirectly distinguishing from single-entity tools like ai_visibility_check. However, it does not explicitly mention alternatives or when-not-to-use, so it stops 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 (readOnly, idempotent, non-destructive), the description discloses significant behavioral details: partial failure degradation, 5-30s delays for new bundlephobia versions, and the sources_failed field. This is exactly the kind of context annotations don't capture.

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

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

The description is long but every sentence carries distinct value: purpose, use cases, output shape, ecosystem limitations, and failure behavior. It's densely packed with no redundant or filler content, and the key purpose is front-loaded.

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

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

With no output schema, the description fully enumerates the returned summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min/gz, dependency_count, has_esm, tree_shakeable), plus advisory details, links, and alternative versions. It also covers edge cases like timeouts and ecosystem fallback, making it complete for an agent to invoke and interpret results.

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

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

Input schema already documents both parameters with 100% coverage, including version default behavior and scoped-package acceptance. The description adds no parameter-level information beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

Description is explicit: it's a composite 'should I add this npm package to my project' check aggregating deps.dev and bundlephobia data. The verb 'scan' plus the named sources and output fields clearly distinguish it from sibling tools like validate_claim or deep_research.

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

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

Gives direct usage triggers: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states ecosystem constraints and points to deps.dev:version as an alternative for non-NPM ecosystems, providing both when-to-use and when-not-to-use.

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

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

The description discloses the underlying algorithm (BGE-base-en embeddings + cosine over 500-char overlapping windows), the truncation behavior at 200K characters, and the nature of results (passages with character offsets and similarity scores). These details go well beyond the readOnlyHint and idempotentHint annotations, giving the agent a precise model of the tool's behavior.

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

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

The description is fairly long but well-organized; each sentence contributes operational value. There is minor redundancy (e.g., 'saves context' and 'returns only the passages that matter' convey a similar idea), but the overall structure is scannable and front-loaded with the core purpose.

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

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

With no output schema, the description compensates by explicitly describing the return format: top-N passages with character offsets and similarity scores. It also covers constraints (200K char cap, truncation flagging) and the integration point with ask_pipeworx_grounded, providing sufficient context for correct selection and invocation.

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

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

The schema already documents all three parameters, but the description adds meaningful context by clarifying that 'text' is already-pulled content, reinforcing the character cap, and giving concrete query examples. The windowing algorithm is an additional detail that enriches parameter understanding, though some redundancy with the schema exists.

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 'Semantic search INSIDE a fetched record', clearly identifying the verb (search) and resource (a fetched record) while distinguishing it from sibling tools like ask_pipeworx by emphasizing it operates on user-supplied text. It also specifies the returned artifacts (top-N passages with offsets and similarity scores), making the purpose unmistakable.

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

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

The description explicitly states when to use this tool: 'Use when the record is too big to cram into the prompt.' It also names a complementary tool (ask_pipeworx_grounded) and outlines a workflow, providing clear guidance on how this tool fits among 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 annotations (write, idempotent, non-destructive), the description reveals auth requirements, the return value, always-on feed behavior, SMS verification and rate cap, and webhook details (though webhook is only in the schema). It adds substantial behavioral context.

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

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

The description is dense but well-organized: purpose, auth, types, delivery. It is not overly verbose, though the long list of types and channels could be seen as a bit lengthy. Every sentence carries useful information.

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

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

The description omits the webhook delivery channel and two subscription types (patent_grant, clinical_trial) that appear in the schema. It presents 'Supported types:' as exhaustive, which is misleading. The schema makes up for these gaps, but the description is not fully complete on its own.

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

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

Schema coverage is 100%, but the description enriches params with concrete examples (e.g., sec_8k items meaning officer change, polymarket_edge topic 'fed', fred_series series_id) and clarifies delivery semantics. It adds value beyond the schema's property descriptions.

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

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

The description clearly states the verb 'Create' and the resource 'subscription to a live-data event stream', and specifies it returns the new subscription id. This distinguishes it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts.

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

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

The description provides clear context on when to use the tool (to create a monitoring subscription) and includes a critical prerequisite: requires a Pipeworx OAuth account. It also explains delivery options and constraints, but does not explicitly contrast with alternatives like recent_alerts for one-time pulls.

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

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

Even though annotations already declare this as read-only, idempotent, and non-destructive, the description adds meaningful behavioral context beyond annotations: it explains that the tool draws from the live catalog, returns exact tool+argument shapes, and serves as a meta-tool learning resource. This enriches the agent's understanding of how the tool behaves without contradicting annotations.

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

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

The description is dense but well-structured: it opens with natural language examples, then explains the return format, then gives invocation guidance. Every sentence contributes to usability, and the structure front-loads the core purpose before diving into details. It is appropriately sized for the tool's complexity.

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

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

Given that the tool has no output schema, the description fully explains what to expect: category-bucketed example questions with tool and argument shapes. It also covers both invocation modes (no arguments vs. topic) and the tool's role in onboarding. This is complete for a simple, read-only 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% for the one parameter, but the description adds valuable semantic guidance: it provides concrete examples of valid topic values (finance, pharma, betting) and explains the behavior of omitting the argument (cross-category spread). This goes beyond the basic schema description and helps the agent select the right input.

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: it is an onboarding entry point that returns category-bucketed example questions about what Pipeworx can do. It uses a specific verb (suggest) and resource (questions to ask Pipeworx), and distinguishes itself from sibling tools like ask_pipeworx by noting it is the tool to use first when you don't yet know what to ask.

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

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

Provides explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains optional topic filtering and when to omit arguments, which clearly situates the tool relative to alternatives.

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

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

Annotations already indicate a non-destructive, idempotent write operation. The description adds valuable context: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This explains the exact side effect beyond what annotations convey.

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

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

Three sentences, each earning its place: action, ownership constraint, and deactivation behavior. No fluff or redundancy; the description is front-loaded and efficient.

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

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

For a simple single-parameter tool with annotations present, the description covers ownership and the non-destructive side effect. It does not mention return values or error cases, but the tool's simplicity and schema coverage make it adequately complete.

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

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

The schema covers the single parameter fully with a description ('Subscription id (uuid) returned by subscribe'). The tool description adds no additional parameter details, so the baseline of 3 is appropriate given the 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 'Cancel a subscription by id', which is a specific verb and resource. It distinguishes from siblings like 'subscribe' (creation) and 'list_subscriptions' (listing). The title 'Unsubscribe from Alerts' reinforces the purpose.

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

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

The description mentions ownership enforcement, which implies a prerequisite, but it does not explicitly state when to use this tool versus alternatives, nor does it suggest reading subscriptions first. Context is clear but no exclusions or alternative guidance is given.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context: the two internal pipelines (SEC EDGAR with exact percent-delta math, and grounded with verbatim evidence), the specific verdict set, and the inclusion of pipeworx:// citations. This goes beyond the annotations, though it does not cover failure modes or latency.

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

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

The description is dense yet efficient. It opens with trigger phrases, states the purpose, explains the two routing paths, and summarizes the output and performance benefit. Every sentence contributes value, and the structure flows logically from triggers to behavior to results.

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

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

The description fully covers the tool's capability, return payload, routing logic, and usage context. Since there is no output schema, the description adequately explains what the tool returns (verdict, actual value with citation, reasoning). It also mentions the tolerance mechanism implicitly. For a tool with only two parameters and no nested objects, this is complete enough 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?

The input schema already provides 100% coverage for both parameters with clear descriptions and examples (claim and tolerance_pct). The description adds some implicit context about tolerance via 'approximately_correct' and 'exact percent-delta math', but it does not meaningfully elaborate on the parameters themselves. Per the rubric, baseline is 3 when schema coverage is high, and the description does not elevate beyond that.

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: natural-language claim verification against authoritative sources. It provides specific trigger phrases, defines the scope ('check whether something a user said is factually correct'), and details the verdict categories. It distinguishes itself by mentioning the SEC EDGAR fast path versus the grounded pipeline, making it distinct from generic research or question-answering 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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides a clear routing rule for company-financial claims versus all other factual claims. It also highlights a key benefit (replaces 4–6 sequential calls), but does not name alternatives or exclude specific sibling tools, 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.