flood

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

Annotations already indicate read-only, idempotent, non-destructive behavior, which the description aligns with. Beyond that, it adds value by disclosing the default model (Workers AI Llama-3.3-70b, free), the BYO-key cost implication for Anthropic calls, and the return structure. This is useful context that annotations do not cover.

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

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

The description is three sentences, each with a distinct purpose: main functionality, model/cost details, and typical use cases. It is front-loaded with the core action and avoids redundancy with the schema.

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

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

With no output schema, the description adequately explains the return format ('per-model {score, confidence, signals, raw_response} + a combined view') and covers the key input variants. It could be more explicit about what the 'combined view' contains (e.g., average score, highlights), but overall it gives enough context to understand the tool's 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?

Schema coverage is 100%, so the baseline is 3; the description adds meaningful detail by naming the default model behind 'workers-ai' and explaining the cost/behavioral implication of passing `_apiKey`. While the schema already covers basic parameter purposes, the description clarifies defaults and the 'free vs. paid' choice.

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

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

The description clearly states the tool's purpose with a specific verb ('Probe'), a defined resource ('one or more LLMs'), and a measurable outcome ('score visibility (0-100) per model'). It also differentiates itself from siblings like 'ask_pipeworx' or 'scan_competitor_ai_presence' by explicitly focusing on LLM awareness scoring rather than general questions or competitor scanning.

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

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

The description gives clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to pass `_apiKey` (to also probe Anthropic, with a cost caveat). However, it does not explicitly name alternative tools to use instead for those scenarios, so it stops short of full exclusion guidance.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses useful behavior: it routes to 5,767 tools across 1,506 sources, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict the annotations.

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

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

The description is front-loaded and informative, but it is wordy and includes a garbled artifact: 'use deep_research when you need more, excuse me, a broad multi-step published-report style answer'. The examples and routing guidance are valuable, but the structure would benefit from trimming.

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 still tells the agent what to expect: a structured answer with citation URIs. It covers domain scope, examples, and routing to sibling tools. It does not discuss limits, cost, or the ask_pipeworx_beta sibling, but for a read-only router tool this is fairly 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 input schema already covers all parameters at 100%, including six aliases for the single 'question' field. The description adds example queries and trigger phrases, but it does not add meaningful detail about parameter formatting, constraints, or edge cases, so the schema-coverage baseline of 3 is appropriate.

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

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

The description is explicit: this tool routes natural-language questions to thousands of verified data sources and returns structured answers with citations. It names concrete question types and examples, and it clearly distinguishes itself from 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?

The description gives strong when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks ...', and 'START HERE for most questions'. It also tells when to prefer ask_pipeworx_grounded and deep_research, making the decision boundary explicit.

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

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

Even with annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description adds valuable live behavioral context: candidate routing improvements are enabled in production when under test, and the last candidate was retired on 2026-07-26, so the tool currently behaves identically to ask_pipeworx. It also clarifies that there is no degraded fallback—'this IS a full working router'—which is exactly the kind of behavioral nuance an agent needs before invoking.

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

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

The description is four sentences and every sentence earns its place: identity, current experimental status, usage guidance, and a clarification that it is fully functional. The most decision-relevant information—'currently matches ask_pipeworx exactly'—is front-loaded in the second sentence. There is no filler or repetition of schema content.

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

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

Given the tool's complexity as a router over 5,767 tools, the description is remarkably complete: it states parity with ask_pipeworx, the experimental nature, current status, and how results are used. It does not describe the actual response shape beyond 'same response shape' as ask_pipeworx, but since ask_pipeworx is a directly available sibling, this cross-reference is sufficient for an agent to know what to expect.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema already documents the main 'question' parameter and the aliases q, text, and input. The description only says 'same arguments' as ask_pipeworx, which reinforces interoperability but does not add new semantic meaning beyond the schema. It is sufficient but not enhanced by the description.

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

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

The description opens with a clear identity statement: 'Beta version of ask_pipeworx' and defines it as an 'identical universal router' with the same tools, arguments, and response shape. It immediately distinguishes this tool from the stable ask_pipeworx sibling by describing the experimental routing edge, and from grounded variants by matching the standard ask_pipeworx interface. An agent can tell exactly what resource this operates on and how it differs from nearby siblings.

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

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

The description gives explicit selection guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the evaluation context—results are compared against the stable router to decide merges—and notes that currently no candidate is active so behavior matches ask_pipeworx exactly. It does not explicitly state a when-not-to-use condition, but 'beta' and 'experimental edge' plus the 'when you want the newest routing' criterion make the intended use 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 mark the tool readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavior beyond that: it returns either a success payload with evidence verbatim quote and confidence, or an explicit refusal with a closed set of refusal_reason values. It also discloses that the answer is extracted only from the tool result, which directly supports the 'hallucination-resistant' claim. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: it states the mode, the routing relationship, the exact return contract, the refusal contract, the usage trigger, and the cost tradeoff. The structure front-loads the headline behavior and ends with actionable guidance. No fluff.

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

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

With no output schema, the description fully specifies the return value shape, including key fields and possible refusal_reason values. It also covers when to use the tool, when not to, and the extra call cost. For a tool with one meaningful parameter and rich annotations, no important operational context is missing.

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

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

Schema coverage is 100%, with all six params documented as aliases for 'question.' The description does not add parameter-level detail, but it doesn't need to: the schema fully explains the one meaningful semantic parameter. The description's mention of 'fills arguments' refers to internal routing rather than the agent-facing input, so no additional parameter meaning is expected.

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 purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It clearly differentiates from the sibling ask_pipeworx by emphasizing evidence-grounded extraction and refusal behavior, so an agent can distinguish this tool from alternatives without reading the schema.

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

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

Usage is explicit: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It names the sibling alternative, gives the selection condition, and even flags the extra LLM call cost as a reason to prefer the cheaper sibling.

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, and non-destructive behavior, but the description goes far beyond: it discloses resolver confidence contracts, low-confidence short-circuiting, closed-market handling, wide-spread illiquidity flags, and cancellation-rule risk with practical implications. This is rich behavioral context that agents need beyond the annotations.

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

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

The description is long and dense, but it earns its length by covering many critical edge cases. It is structured with clearly labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Some redundancy exists, but overall it balances detail with organization.

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

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

Even without an output schema, the description thoroughly explains the expected result structure (market, analysis, evidence), resolver contract, parent-event extraction, news fields with fallback behavior, and safety routes. It also provides actionable guidance for dealing with low-confidence matches and cancellation rules. This is nearly exhaustive for a complex tool.

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

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

The schema already covers all three parameters with descriptions, so the baseline is 3. The description adds value by giving input format examples (slug, URL, question text) and showing how the market parameter triggers fan-out to category-specific data packs. It does not add much about depth or include_raw, but the examples and fan-out explanation strengthen 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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', with specific verbs and resources. It also gives concrete input examples (slug, URL, question text) and distinguishes itself from sibling tools by focusing on bet research fan-out. The 'Use for' phrases reinforce its 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?

The description explicitly lists when to use the tool: 'Use for "should I bet on X"...' and provides clear functional scope. However, it does not name specific alternatives or exclusions relative to sibling Polymarket tools, so it lacks the when-not-to-use differentiation that would earn 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=true and idempotentHint=true. Beyond that, the description adds significant behavioral detail: data sources per type (SEC EDGAR/XBRL vs FAERS/FDA), off-calendar fiscal year handling, sorting by primary metric, and citation URIs in output. This exceeds the safety info provided by 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 contributes: query examples, capability, data specifics, sorting behavior, output format, and efficiency claim. It is front-loaded with query patterns and maintains readability despite the volume of information.

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

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

For a tool with no output schema, the description covers the essential context: supported entity types, data sources, sorting, output format (paired data + citation URIs), and fiscal year nuance. It also explains the efficiency benefit over sequential lookups, making it complete for selection and invocation.

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

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

Schema coverage is 100% with detailed descriptions for both parameters (enum for type, min/max for values). The description adds value by explaining what each type retrieves (revenue/net income/cash for company; FAERS counts for drug) and how results are sorted, going beyond the schema's syntactic definitions.

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

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

The description uses a specific verb ('compare') and resource ('companies or drugs') with a clear scope ('2–5... in ONE parallel call'). It distinguishes from siblings by explicitly positioning itself for comparisons, reinforced by example query patterns like 'X vs Y' and 'rank these companies'.

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 strong guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. This clearly states when to use it, though it does not explicitly name alternative sibling tools (e.g., entity_profile) for non-comparison cases, leaving the exclusion implicit.

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

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

Annotations already mark it read-only, idempotent, and safe. The description adds substantial behavioral detail: account requirements and paid tier for 'thorough', internal decomposition into facets, parallel routing to 5,767 tools, and a findings packet with evidence, confidence, source, fetched_at, stable citations, and explicit gaps[] rather than invented answers.

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 information-rich rather than padded; each clause communicates a distinct constraint or capability. It is slightly long and repeats the ask_pipeworx alternative twice, but both repetitions serve different routing conditions (unsigned-in vs. single lookup), so the structure remains effective.

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

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

For a complex research tool with no output schema, the description covers the essential operational context: authentication, pricing constraint, data-source scope, what happens internally, what the return packet contains, and when to use a sibling instead. Nothing critical for correct selection or invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by noting that depth 'thorough' requires a paid plan, which is a crucial invocation constraint. It also clarifies that the natural-language 'question' parameter is meant for broad/multi-part questions.

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

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

The description identifies a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources... in ONE call.' It clearly differentiates from open-web search and from ask_pipeworx by stating this is NOT open-web search and by naming ask_pipeworx for single 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?

It gives explicit alternative routing: 'If you are not signed in, use ask_pipeworx instead,' and 'For a single lookup use ask_pipeworx instead.' It also states the tool is best for broad/multi-part questions over structured data, which tells the agent exactly when to choose 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: returns top-N results with full input schemas, ready to call directly, no second lookup needed. This tells the agent exactly what to expect in the response, which is not conveyed by the annotations alone.

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 every sentence serves a purpose: purpose, usage context, return value detail, and a strong 'call this FIRST' directive. The domain list is somewhat extensive but directly helps the agent decide relevance. No fluff, but slightly over the minimal length, earning a 4 rather than 5.

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 adequately explains the return value (top-N tools with names, descriptions, and full input schemas). It also covers when to use it, and the annotations cover safety. For a discovery tool, this is complete: purpose, usage, and expected output are all addressed, with no obvious gaps.

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

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

Schema coverage is 100%, so the schema fully documents the parameters. The description mentions 'top-N' and 'query' as natural language, but these are already present in the schema descriptions. The description does not add significant new meaning about parameter syntax, types, or aliases beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Find tools by describing the data or task." It clearly distinguishes this as a meta-tool for browsing/discovering other tools, and enumerates many concrete domains (SEC filings, FDA drugs, FRED, etc.), making it unmistakable what this tool does and how it differs from sibling tools.

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

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

The description explicitly states when to use: "Use when you need to browse, search, look up, or discover what tools exist for..." and "Call this FIRST when you have many tools available and want to see the option set (not just one answer)." This provides clear context and implies a distinction from using a specific tool directly, though it doesn't list explicit exclusions.

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

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

Annotations already mark it read-only, idempotent, and non-destructive, so the bar is lower. The description adds significant behavior context: soft-fail for USPTO, sources_used/sources_failed semantics, empty sections meaning real 'no data', and private-company resolution returning resolved:false with a notes line. No contradiction with annotations.

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

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

The description is a dense, run-on paragraph with many clauses and parentheticals. It is front-loaded with examples and the core purpose, and all content is relevant given the tool's complexity, but it would benefit from bullet points or clearer segmentation. Length is justified but structure hurts readability.

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

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

With no output schema, the description must enumerate return fields, and it does: cik, company_name, resolved_from/resolved_to, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/failed. It also covers edge cases (private companies, expected empty FDA section, USPTO sunset) and explains the parallel-call nature. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples ('AAPL', '0000320193', 'Moderna'), clarifying that type is interchangeable, and explaining that names resolve via SEC EDGAR's company-name match. It also covers the private-company case, which the schema does not.

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 explicitly states the tool builds a 'full cross-source profile of a US public company in ONE parallel call' with example queries like 'research Acme' and 'brief me on Tesla'. It distinguishes itself from chaining single-pack SEC/XBRL/news lookups, making its role clear relative to sibling tools like resolve_entity 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?

It gives an explicit directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This provides a clear when-to-use condition and names the alternative pattern. It does not explicitly state when not to use the tool (e.g., for a single-aspect lookup or a private company), but the holistic-view condition implies the boundary.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate safety. It adds minimal behavioral context ('clear sensitive data') but does not disclose potential error behavior or return value. This is consistent with annotations, and the description carries only light extra weight 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 three concise sentences: a clear operation statement, usage conditions, and a sibling pairing note. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a simple single-parameter delete tool with annotations covering destructive and idempotent traits, the description covers purpose, usage timing, and related tools. It does not mention return behavior, but given the tool's simplicity and lack of output schema, this is not a significant gap.

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% (one param 'key' with description 'Memory key to delete'). The description merely repeats 'by key' without adding semantic detail beyond the schema, so it meets the baseline but adds no extra value.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' It clearly distinguishes this tool from its siblings (remember and recall) by specifying the delete operation, and the addition of 'by key' indicates the target mechanism.

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

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

The description gives explicit usage conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references siblings with 'Pair with remember and recall,' providing clear situational guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing a safe read-only profile. The description adds meaningful behavioral context beyond those annotations by explaining the tool fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format. 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 two sentences long and front-loads the core action. Every clause adds value: the purpose, the process, the output format, and the use cases. There is no fluff or repetition of schema details.

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?

This is a simple, focused tool. The description explicitly states the output format ('single text blob ready to drop at site-root/llms.txt') and covers the main input scope ('any URL') and optional max_links. With no output schema, the description sufficiently explains return values and enough context for selection and invocation.

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

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

Schema coverage is 100%, with both url and max_links already described in the input schema. The description mentions 'any URL' and the output format, but it does not add parameter-specific details beyond what the schema provides. Since the schema does the heavy lifting, a baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes this tool from siblings by naming the exact output and the AI crawlers it targets. The process (fetch, extract, emit) and the deliverable ('single text blob') make the purpose unambiguous.

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

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

The description provides clear use-case scenarios: 'getting a client's site indexed by AI', 'drafting llms.txt for your own project', and 'auditing how an AI crawler would see a competitor'. It does not explicitly exclude any alternatives or mention when not to use it, but the context is clear enough for an agent to decide when this tool is appropriate.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by specifying the nature of the data returned: multi-day forecast with current/mean/peak projections and severity assessment. This goes beyond the annotations and helps the agent understand what to expect.

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

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

The description is three sentences and front-loaded with the purpose. The second sentence ('Returns discharge statistics and severity assessment') is slightly redundant with the first, but each sentence contributes useful information. It is efficient without being excessively 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?

With output schema present and annotations covering safety, the description is complete for tool selection and invocation. It clearly states the input (location) and the purpose (flood risk/timeline), and the output schema defines return values. No further context is needed.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'location' but does not elaborate on forecast_days or provide additional parameter context beyond the schema. It adds no meaningful parameter semantics beyond what is already in the schema.

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

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

The description uses a specific verb 'Get' with a clear resource: 'multi-day flood forecast for a location,' and details the outputs (current, mean, and peak river discharge projections, discharge statistics, severity assessment). This distinguishes it from siblings like get_river_discharge, which likely focuses on current discharge only.

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: 'Use to evaluate flood risk and timeline.' It provides clear context for the primary use case, though it does not name alternative tools or provide exclusions. This qualifies as clear context without explicit alternatives, warranting a 4.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context about units and timestamps but does not clarify openWorld implications or any additional behavioral details 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?

Three sentences, front-loaded with the core function, then unit and use case. No redundancy or unnecessary details; every sentence contributes 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?

With a complete input schema and an output schema present, the description covers the primary purpose and use case. Minor gap: no mention of the related flood forecast tool, but the description is sufficiently complete for a simple read-only data fetch.

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 parameters are fully described in the schema. The description adds the unit of measurement and forecast nature but does not elaborate on parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool retrieves daily river discharge forecasts in cubic meters per second for a location, with a specific resource and verb. It differentiates from siblings by specifying discharge rather than flood forecasts, though it does not explicitly distinguish from get_flood_forecast.

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

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

Provides a usage context: 'Use to monitor water flow rates for flood risk assessment.' However, it does not mention when not to use it or compare with the closely related sibling get_flood_forecast, leaving some ambiguity for tool selection.

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds useful behavioral context by specifying the caller scope and the exact return fields, which is valuable since no output schema exists. It does not contradict any annotation.

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

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

The description is two sentences with no fluff. It front-loads the purpose, then lists return fields, then provides usage guidance. Every sentence earns its place.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It covers purpose, return fields, caller scoping, and practical use cases. No significant gaps.

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

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

The input schema has 100% coverage for the single optional parameter include_inactive. The description mentions 'active subscriptions' which implies the default, but adds no new semantics beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb and resource: 'List the caller's active subscriptions.' It also lists the returned fields (id, type, params, etc.), making the tool's functionality concrete and distinguishing it from subscribe/unsubscribe siblings.

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

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

The description explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly ties to the sibling tools subscribe and unsubscribe, offering clear when-to-use guidance without restating 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 are all false, so the description carries full burden. It discloses rate-limiting ('5 per identifier per day'), free/no quota impact, the claim_token flow (returned when filing without an account, can be passed later to read status), and human digestion cadence ('team reads digests daily'). No contradictions.

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

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

The description is lengthy but nearly every sentence adds essential operational detail (criteria, exclusions, claim_token mechanics, rate limits, roadmap impact). It is front-loaded with the core action. It could benefit from paragraph separation for scannability, but there is minimal redundancy.

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

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

Despite no output schema and a small parameter set, the description covers all invocation modes (original filing, claim_token follow-up), constraints, what not to do, and follow-up behavior. It fully equips an agent to decide and invoke correctly, even including edge cases like non-Pipeworx tools.

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

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

Schema coverage is 100%, but the description adds practical nuance beyond field names: explains how claim_token changes the call (pass with no other arguments), instructs to describe issues in terms of Pipeworx tools/packs rather than user prompts, and clarifies message specificity expectations. This enriches the bare schema.

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

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

The description opens with a clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates explicit use cases (bug, feature/data_gap, praise), which differentiates it sharply from sibling research/query tools like deep_research or discover_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?

Provides explicit when-to-use and when-not-to-use guidance: use for bugs, feature gaps, and praise, but explicitly NOT for tools from other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). Even includes a 'not sure?' heuristic referencing Pipeworx tool names.

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 mark this as readOnly, openWorld, idempotent, and non-destructive, the description adds valuable behavioral context: it is derived from CF analytics-engine, contains no PII, only exposes (pack, tool, count), and is cached 5min-1h depending on window. This goes well beyond the annotations and helps set expectations about freshness and privacy.

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

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

The description is concise yet complete: it names the output, the windows, the use cases, and important caveats (no PII, caching) in a compact format. The numbered use cases make it easy to scan, and every sentence adds value without redundancy.

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

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

This is a simple read-only tool with one optional parameter and no output schema, but the description fully covers what the agent needs: what is returned (top tools, top packs, total call volume), how to choose a window, why it is useful, privacy characteristics, and caching behavior. The annotation set is strong, and the description fills any remaining gaps.

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

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

The input schema has 100% coverage for the single optional 'window' parameter, including enum values and a meaningful description ('Shorter windows surface what's hot right now; longer windows show steady-state demand'). The tool description only mentions the windows without adding meaningful new semantic detail, so the baseline of 3 is appropriate because the schema already carries the weight.

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

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

The description clearly states what the tool does: it returns trending tool/pack usage and total call volume on Pipeworx. It is specific about the resource ('top tools, top packs, total call volume') and time windows, and it differentiates itself from siblings like discover_tools by focusing on live usage signals rather than static discovery.

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

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

The description provides explicit use cases ('Useful for: (1) discovering what data sources are hot... (2) confirming a popular tool is the canonical choice... (3) seeing whether your use case aligns...'), which tells the agent when to use it. It does not name alternative tools or exclusion criteria, so it stops short of the 'when-not' guidance that would earn 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?

An annotation already declares readOnlyHint/openWorldHint and destructiveHint=false, but the description adds substantial behavioral context: threshold deviations (>3pp), placeholder filtering rules (>20% returns null), Jaccard similarity ≥0.30, and fill-check details (realizable_edge_pp ≤ 0 means don't trade). It also explains response fields. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and uses scannable labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that improve navigation. However, it is quite long—about 150 words—and could be tightened without losing essential detail, so it's not maximally concise but remains well-structured.

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

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

Given two optional parameters and no output schema, the description is remarkably complete: it covers both modes, return shape (opportunities[], partition_check, fill_check), failure conditions (placeholder >20%), and edge cases (last-trade vs book). It leaves no critical aspect unexplained, making it fully self-sufficient.

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

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

Schema coverage is 100% for both parameters, yet the description goes far beyond the schema by providing concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explaining the mode each parameter triggers, and describing how each mode behaves. This adds meaning well beyond the structured schema.

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

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

The description opens with a clear verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It differentiates itself from siblings by naming polymarket_fill_risk and by explicitly describing the two modes (`event` vs `topic`), which also helps distinguish from related tools like polymarket_edges.

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

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

It gives explicit when-to-use guidance: use `event` for a specific market, `topic` for cross-event scanning, and notes that cross-event mode catches patterns single-event misses. It also directs users to polymarket_fill_risk for custom sizing, clearly delineating an alternative 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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the bar is lower, but the description adds substantial behavioral context: response structure (by_segment, fed_candidates, _diagnostics), model family details, Kelly caps, slippage handling, a 24h-move warning, and KV-level caching keyed on knobs. It clearly explains what the agent should expect and why certain segments may be empty.

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 exceptionally long and dense, but it is front-loaded with the core purpose and structured with clear section markers (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL). Each sentence adds meaningful information that an agent needs to invoke the tool correctly; however, the sheer length and lack of bullet points or line breaks make it less concise than ideal.

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

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

There is no output schema, so the description must explain return values, and it does so thoroughly: it specifies the top-level keys (by_segment, fed_candidates, _diagnostics), the per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and even the funnel counters for diagnosing empty segments. It also explains the caching behavior and Fed signal unreliability, making the tool self-contained for agent use.

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

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

Since schema coverage is 100%, the baseline is 3, but the description goes far beyond schema descriptions by explaining interactions and design rationale. For example, it clarifies why min_kelly does not apply to partition_overround opportunities (they return kelly_fraction_half=0 at parent level), details the slippage_pp subtraction before ranking, and describes how min_partition_leg_kelly applies to per-leg Kelly inside top_legs.

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

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

The description opens with a specific verb+resource ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price'), immediately distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It also names the three output segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), reinforcing its unique scope.

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

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

The tool is explicitly framed as 'Built for "what should I bet on today"' and notes that agents can discover opportunities without paging hundreds of markets, giving clear use context. It also provides a caveat about Fed bets being excluded from ranking and unreliable at meeting-month horizons, but it does not explicitly name alternative tools or state when to avoid this tool in favor of siblings.

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

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

The description goes far beyond the annotations, which already declare readOnly, openWorld, idempotent, and non-destructive. It adds critical behavioral details: response structure (tracked[], expired[], snapshot_dates[]), data source (snapshots on cache-miss), limitations (60-day TTL, gaps due to no scans), and computation basis (daily closes of edge_pp_net, not intraday).

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

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

The description is long but highly structured: it opens with the core purpose, then clearly labels Args, RESPONSE, and LIMITS. Every sentence contributes valuable information—no filler. The format is easy to scan and front-loaded with the main question it answers.

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

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

Despite no output schema, the description comprehensively covers return fields (tracked[], expired[], snapshot_dates[]) with field-level details (e.g., trend options, decay calculation). It also covers data availability (snapshot gaps, TTL) and precision caveats (daily closes, not intraday). This is complete for a telemetry 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 adds extra meaning by explaining 'days' as lookback with defaults and limits, and 'window' as a snapshot family (e.g., 24hr, 1wk, 1mo) with a default. This clarifies semantics beyond the schema, though much is already in the parameter 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: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from siblings like polymarket_edges (which likely provides current edges) by focusing on temporal tracking and decay.

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 strong contextual guidance: it explains that this tool is for understanding edge persistence over time (e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades'). It doesn't explicitly name alternative tools, but the context makes it clear when to use this vs. a current-edge 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 mark the tool as read-only, idempotent, and non-destructive, so the bar for additional behavioral disclosure is met by the description's rich details. It discloses ladder walking, return fields (top_of_book, vwap_fill_price, slippage_pp, per-leg detail, thin_legs[], forced_directional_risk), and the key risk that partial basket fills convert an arb into an unhedged directional position. This goes well 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 long but densely structured with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. Every sentence adds either operational detail, return field clarification, or strategic guidance. The front-loaded purpose sentence and logical grouping make the length appropriate for a tool with two distinct modes.

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

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

Given the absence of an output schema, the description compensates by listing all major return fields for both modes, including verdicts, capture_ratio, thin_legs[], and max_clean_notional_usd. It also covers input requirements, defaults, mode-specific behavior, and risk context. For a tool with this complexity, the description is comprehensive 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?

Although the schema already has 100% coverage for its four parameters, the description adds substantial meaning: it explains when to use `market` vs `event`, defines `side` options for each mode, clarifies `size_usd` as max spend/target proceeds in single-market mode vs settlement notional in basket mode, and lists defaults. This significantly enhances schema-only semantics, especially around mode-dependent interpretation.

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 purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes itself from siblings by explicitly instructing to use this tool before acting on polymarket_arbitrage or polymarket_edges signals, and by detailing two distinct modes (single-market and basket). The verb 'check' plus resource 'CLOB order-book depth' makes the action unambiguous.

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

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

The description provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the critical distinction between single-market and basket modes, including required parameters for each. The warning about theoretical overround on thin books and partial-fill risk gives clear context for why this tool should precede trades.

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

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

The annotations already declare read-only/idempotent/non-destructive behavior, but the description adds substantial behavioral detail: it explains that pairs are matched by token overlap rather than a shared resolution source, that temporal_alignment null means 'could not be computed' rather than confirmed, that spreads are gross of Kalshi fees, and that safety fields can be non-empty even when matched_pairs>0. No contradiction with annotations exists.

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

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

The description is long but densely informative, with clear labels such as TWO MODES, RESPONSE, SAFETY FIELDS, and explicit code lists. Every section serves a real decision purpose, from fee disclosure to skipped-counter semantics, so the length is justified for the complexity.

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

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

There is no output schema, so the description must carry the return-value burden; it does. It details the response shape (leg prices, top_spreads_pp, compatibility fields, flags, temporal_alignment, fees_note, skipped counters) and covers important caveats like gross spreads and unclassified legs never being paired. An agent has enough context to correctly interpret results.

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

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

Schema coverage is 100% and each parameter already has a description, so the baseline is 3. The description adds extra value by explaining that both explicit parameters override the topic-mapped side, that both modes run the identical matcher, and by providing examples like 'fed-decision-in-june-825' and 'KXFED-26OCT'.

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

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

The description opens by defining the exact operation: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also enumerates two distinct modes ('topic' and explicit ticker/slug), which distinguishes this tool clearly from intra-venue siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description gives concrete guidance on when to use each mode, including the 10 pre-mapped topics and the explicit custom-pairing path. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility warnings today. However, it does not explicitly compare against sibling tools or state when to prefer an alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds non-obvious behavior: omitting the key lists all keys, and results are scoped to the caller's identifier (anonymous IP, BYO key hash, or account ID). This goes beyond the schema's 'omit to list all keys' by explaining the scope and listing 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?

Three sentences, front-loaded with the core action, then use cases and pairing. No filler or repetition of schema metadata; 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-optional-parameter, read-only memory lookup, the description covers the action, the list mode, scoping, and related tools. The absent output schema is acceptable for a simple key-value retrieval; there is no hidden complexity needing further disclosure.

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 the single 'key' parameter 100%, including the omission behavior, so the description doesn't need to restate mechanics. It adds illustrative usage ('user's target ticker, an address, prior research notes') that helps an agent decide what values are appropriate to store/retrieve. This extra semantic context justifies a 4.

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

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

The description opens with 'Retrieve a value previously saved via remember, or list all saved keys' — a specific verb and resource that clearly distinguishes it from siblings remember and forget. It names the exact action and scope, leaving no ambiguity about what the tool does.

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

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

'Use to look up context the agent stored earlier... without re-deriving it from scratch' states when to choose this tool. It also names companion tools ('Pair with remember to save, forget to delete'), providing explicit alternatives and context.

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

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

The description discloses a state-changing behavior: 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This contradicts the annotation readOnlyHint=true, which implies no write operations. The contradiction is serious, so a score of 1 is warranted.

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 in the first sentence and then adds concise, useful details in the following sentences. No fluff or redundancy exists; every sentence carries informative value, including the alternative endpoint note.

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

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

Without an output schema, the description adequately covers the return payload (source, citation_uri, raw event payload). It also explains filtering, polling behavior, mark_read side effects, and provides an alternative access URL. The unread_only parameter is not mentioned but is covered by the schema, so the description is complete enough.

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 parameters are already described. The description adds meaning beyond the schema: it explains the consequence of mark_read (next call only newer), clarifies that since is an ISO timestamp, and gives an example type filter. This supplementary detail justifies a score above baseline.

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

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

The description opens with 'Pull fired events from your subscription feed,' which clearly states the action and resource. It distinguishes itself from siblings like list_subscriptions and recent_changes by focusing on fired alerts from a persisted feed.

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

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

The description provides clear usage context: filtering by type and since, setting mark_read to control future outcomes, and noting that polling works fine. It does not explicitly exclude alternative tools, but it does mention an alternative HTTP endpoint for scripts/dashboards, which is helpful 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?

Despite annotations already indicating read-only/idempotent safety, the description adds rich behavioral detail: fan-out to SEC/GDELT/USPTO, fallback and soft-fail behavior, return structure with changes[] grouped by source, and 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?

Dense but highly efficient; every sentence delivers value: query examples, source fan-out, fallback logic, parameter format, return structure, and alternative tool. Front-loaded with common use cases.

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

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

With no output schema, the description compensates by describing the return shape (changes[] grouped by source, total_changes, citation URIs). It also covers source-specific behavior, window semantics, and the key alternative tool, making the tool's operation fully understandable.

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

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

Schema covers all three parameters fully (100% coverage), so baseline is 3. The description reinforces the `since` shorthand and ticker/CIK formats but does not add substantive meaning beyond the schema; it contextualizes rather than extends 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 description clearly states the tool's function: a change feed for a company over a time window, fanning out to multiple sources. It distinguishes itself from sibling entity_profile by specifying static profile vs. change feed.

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

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

Provides explicit natural-language query examples and an explicit 'instead' alternative: 'Use entity_profile instead when you want the static profile'. This gives clear when-to-use guidance.

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

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

The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: scoping by user identifier, persistence differences between authenticated users and anonymous sessions, and the ability to delete via 'forget'. This exceeds what annotations alone convey.

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

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

The description is well-structured and front-loaded, opening with the core purpose and then providing usage triggers, storage details, and companion tools. Every sentence adds value, with no redundancy or filler. Despite being moderately long, it remains concise given the information covered.

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 key-value store with two required parameters and no output schema, the description is complete. It explains the tool's purpose, when to use it, storage model, persistence scoping, and related tools. No critical information is missing for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for both parameters, so a baseline of 3 applies. The description adds meaningful examples beyond the schema by illustrating typical keys ('a resolved ticker, a target address, a user preference') and value types ('findings, addresses, preferences, notes'), enriching parameter understanding without replacing schema details.

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

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

The description clearly states the tool's purpose with a specific verb ('Save') and resource ('data the agent will need to reuse later'). It distinguishes from siblings by explicitly naming 'recall' and 'forget' as companion tools, making the tool's role in the memory workflow clear.

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

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

The description provides explicit use cases ('Use when you discover something worth carrying forward') with concrete examples (resolved ticker, target address, user preference, research subject). It also names alternatives/companion tools ('Pair with recall to retrieve later, forget to delete'), satisfying the highest bar for 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?

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations already present, the description adds substantial behavioral detail: it explains that enrichment degrades gracefully, that ambiguous instrument matches return figi_candidates rather than asserting, that unresolved identifiers appear under `unresolved`, and that each call internally cascades through several lookup endpoints. This goes well beyond what the annotations declare.

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

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

The description is long, but it is front-loaded with query examples and every sentence carries useful information about behavior, supported types, or edge-case handling. It is not maximally concise, yet it avoids filler and organizes the content clearly enough that an agent can extract the key guidance.

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

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

Given there is no output schema, the description carries the full burden of describing what the tool returns. It explains the identifier types returned, source labels, the unresolved-field convention, the figi_candidates ambiguity behavior, and graceful degradation when enrichment services are unavailable. Nothing essential for correct invocation or result interpretation appears to be missing.

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

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

Although the input schema already covers both parameters at 100%, the description adds crucial semantic detail, especially for the `value` parameter: pass the ENTITY NAME ONLY, for a bond that means the issuer exactly as printed, never the full noun phrase. It also explains what the `type` enum implies for the resolution path, which materially helps an agent invoke the tool correctly.

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

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

The description states a specific verb and resource: it resolves a user-spoken name to canonical/official identifiers that other tools require as input. It immediately distinguishes this tool from siblings by positioning it as the identifier-lookup step, with concrete example queries and supported types. The 'Use FIRST whenever you have a name but need an ID' line makes its role unmistakable.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID,' and it clarifies that a call to resolve_entity replaces 2-3 manual lookups. It does not explicitly name alternative sibling tools or state when not to use it, but the trigger conditions and scope are clearly conveyed through examples and supported types.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses the internal process (probing each entity via ai_visibility_check), the ranking behavior, and the return structure (ranked list with score, confidence, signal density). This adds meaningful behavioral context not available in annotations alone.

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

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

Three sentences, each earning its place: the first states the core purpose, the second explains the process and output, and the third gives a concrete use case. No redundancy or filler; front-loaded with the primary action.

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

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

Given the tool's moderate complexity (4 parameters, no output schema), the description fully covers when to use it, how it works, and what it returns. It even mentions the output fields (score, confidence, signal density) that would otherwise be absent, making it 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?

The input schema already provides 100% coverage of all parameters with detailed descriptions (including the first-entity-as-subject convention). The description adds a brief narrative about how entities are processed but doesn't introduce semantic information beyond what the schema offers, meriting the baseline 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 uses a specific verb 'Compare' with a clear resource 'AI visibility across multiple entities' and explicitly distinguishes itself from the sibling tool ai_visibility_check by stating it probes each entity with that tool. It also specifies the outcome (ranked list, most/least recognized), leaving no ambiguity about the tool's function.

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

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

The description states it is 'Useful for competitive AI-marketing audits' and provides a concrete example question, clearly indicating when to use it. While it doesn't explicitly name an alternative for single-entity checks, the phrase 'Probes each entity with ai_visibility_check' implies ai_visibility_check is for individual probes, so the differentiation is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important runtime behavior: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This context helps agents set expectations and handle errors appropriately, exceeding 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 single dense paragraph but every sentence adds value: purpose, use case, return fields, ecosystem scope, and failure behavior. It is front-loaded with the core check and avoids redundancy with the schema or annotations.

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 (composite fan-out, multiple return fields, external service dependencies), the description covers all key aspects: data sources, exact return fields, ecosystem boundaries, latency, and degradation behavior. Without an output schema, this description fully compensates.

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 both parameters completely (npm package name, scoped package acceptance, version default). The description adds no new semantic information for the parameters—only contextual behavior like latency. With 100% schema coverage, this is the baseline score.

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

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

The description opens with a clear composite purpose: 'should I add this npm package to my project' check in ONE call, and explicitly names the external sources (deps.dev and bundlephobia) and the data categories. This distinctly separates it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which target different domains.

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 trigger phrases: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states an exclusion for non-NPM ecosystems and directs users to deps.dev:version directly, providing a clear alternative.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds significant behavioral context: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-char windows, and caps input at 200K chars with truncation flagging. This goes well 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 four sentences, each dense with information and no redundancy. It front-loads the core action, then adds usage, technical details, and limitations. 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?

Despite no output schema, the description explains the return format (passages with offsets and similarity scores). It covers the use case, technical mechanics (embeddings, window size), limitations (200K cap, truncation flag), and sibling pairing. This is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds useful semantic context beyond the schema: it clarifies 'text' as already-fetched content (e.g., SEC 10-K body), gives natural-language query examples, and mentions 'top-N' which relates to the limit parameter. This additional context elevates the score above the baseline.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes this tool from siblings by emphasizing the search-inside-fetched-text use case, and it explicitly contrasts with ask_pipeworx_grounded. The examples (SEC 10-K body, article) reinforce 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 gives explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt.' It also provides a direct pairing with a sibling tool (ask_pipeworx_grounded), explaining the workflow: 'fetch with the gateway, ground over the relevant passages.' This is clear, actionable 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?

Despite annotations (readOnlyHint=false, idempotentHint=true), the description adds substantial behavioral detail: auth requirement, return value, always-on feed, email/sms constraints, phone verification, and daily cap. This goes well beyond the annotations with no contradictions.

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

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

The description is dense but well-structured, front-loaded with the purpose, then types and delivery options. Every sentence contributes; however, it is lengthy and could be improved with bullets, so it doesn't reach a 5.

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

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

For a complex tool with 3 params, nested objects, 5 subscription types, and no output schema, the description covers the essentials: purpose, auth, types, delivery, return value, and key constraints. It is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples (e.g., items:['5.02'] = officer change) and clarifying param semantics beyond the schema descriptions. That extra context justifies a 4.

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

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

The description clearly states a specific verb ('Create') and resource ('a proactive monitoring subscription to a live-data event stream'), and distinguishes from siblings like list_subscriptions and unsubscribe. It also mentions the return value (subscription id).

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?

Clear context is provided: requires a Pipeworx OAuth account, supported types, delivery channels, and an alternative for pulling feed (recent_alerts). However, it does not explicitly say when not to use this vs. alternatives like unsubscribe or list_subscriptions, 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: it explains that calling with no arguments returns the full spread, passing a topic focuses results, and that outputs are drawn from the live catalog of thousands of tools.

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 detailed but well-structured, starting with example questions, then describing output and usage. It is slightly longer than necessary due to listing all categories both in the description and the schema, but every sentence contributes useful guidance.

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

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

For a tool with one optional parameter and no output schema, the description is remarkably complete. It explains the purpose, the input behavior, the output nature, and the intended first-use scenario, leaving no major gaps for the agent.

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

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

Schema description coverage is 100%, and the schema already documents the 'topic' parameter with allowed values and the 'omit for cross-category spread' behavior. The description repeats this information without adding new meaning, so the 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 identifies this as the onboarding entry point for an agent that wants to know what to ask Pipeworx. It states it returns category-bucketed example questions with the exact tool and argument shape, distinguishing it from siblings like ask_pipeworx or discover_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 to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides a clear usage context, though it does not explicitly mention alternatives or when not to use it, leaving a small gap.

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 critical behavior beyond the annotations: the row is deactivated not deleted, ownership is enforced, and historical events remain available via recent_alerts. This aligns with annotations like destructiveHint=false and adds meaningful context without contradiction.

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

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

The description is two concise sentences, front-loaded with the core action and followed by important caveats. Every sentence earns its place and there is no redundancy.

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

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

For a simple one-parameter mutation tool with no output schema, the description covers the operation, ownership restriction, and side effects. No critical information is missing given the tool's low complexity.

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

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

The input schema fully documents the single id parameter as a subscription id returned by subscribe, so the description's 'by id' adds no additional semantic value. Baseline 3 is appropriate given complete 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 opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly distinguishes itself from siblings like subscribe or list_subscriptions. The scope is unambiguous.

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

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

The description makes it clear this is for canceling a subscription and adds a key usage constraint: ownership is enforced. It does not explicitly mention alternative tools, but the 'by id' and 'recent_alerts' references provide enough contextual guidance for when 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 only indicate read-only, open-world, idempotent, and non-destructive. The description adds crucial behavioral context: the distinction between could_not_verify (check didn't happen, must not be used as evidence) and unsupported (no source found), plus the existence of verification_error with stage/detail. This is genuinely useful beyond annotations.

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

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

The description is longer than ideal but front-loaded with query pattern examples and ends with an important caller-specific warning. Every sentence adds meaningful information; the length is justified by 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?

No output schema exists, so the description compensates by listing the full verdict set, citation format, reasoning output, and error semantics. It also explains the fallback routing logic and the distinction between could_not_verify and unsupported, making it complete for a claim verification 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% and both parameters already have rich descriptions covering tolerance override and default behavior. The tool description adds only marginal color like 'exact percent-delta math' and 'capped at 5', which is already in the schema. No significant added 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 uses a specific verb+resource: verifies natural-language claims against authoritative sources. It distinguishes itself from sibling tools by listing trigger phrases, describing the financial fast path vs grounded fallback, and noting it replaces 4–6 sequential calls.

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?

Clearly states 'Use whenever the agent needs to check whether something a user said is factually correct' and gives detailed routing logic for company-financial vs other claims. It doesn't explicitly name alternative tools or when-not-to-use, but the 'replaces sequential calls' implies a preferred single-call approach.

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