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?

Annotations already declare readOnlyHint and non-destructive behavior. The description adds context about dynamic routing to many sources, stable citation URIs, and 'one fast call' performance. It does not contradict annotations, and the added behavioral details (e.g., citation format, routing) go beyond the schema.

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

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

The description is lengthy but front-loaded with 'PREFER OVER WEB SEARCH' and structured logically: what it does, when to use, examples, alternatives. It uses space efficiently to cover a broad tool scope, though some redundancy exists (e.g., 'even if web search could also answer it').

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

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

For a complex routing tool with no output schema, the description is remarkably complete: it explains the tool's purpose, scope, examples, alternatives, and return format (structured answer with citations). It could mention failure/edge cases, but given the breadth and the strong annotations, it is sufficient for correct selection and invocation.

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

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

Schema coverage is 100% for the single 'question' parameter with aliases. The description adds examples of questions but no additional parameter semantics beyond what the schema already states. Baseline of 3 is appropriate since the schema carries the full parameter burden.

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

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

The description clearly states the tool routes questions to one of 5,462 tools across 1,419 verified sources and returns structured answers with citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives, and by stating it should be preferred over web search.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...' with specific trigger phrases. Also states when NOT to use it ('Step up only when needed') and names the alternative tools for different scenarios, including grounded answers and multi-part research.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations: the experimental routing can change live when a candidate is under test, currently no candidate is active, and it is a full working router (not a fallback). This gives the agent important behavioral expectations without contradicting annotations.

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

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

The description is three sentences, each adding distinct value: it defines the tool, clarifies current status, and gives usage guidance. It is slightly longer than ideal but remains efficient and well-structured for the complexity involved.

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

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

Given the complexity (a universal router with many tools) and lack of output schema, the description adequately covers current behavior, usage, and relationship to the stable router. It mentions the same response shape as ask_pipeworx, which provides indirect output expectations. It does not detail error handling or how to detect active candidates, but these are not critical for basic 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?

The schema covers 100% of parameters: all six are aliases for 'question', which has a clear description. The tool description adds no additional parameter-level meaning, but the schema already does the heavy lifting, 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 states this is a beta version of ask_pipeworx, an identical universal router with the same 5,462 tools, arguments, and response shape, but with candidate routing improvements. It distinguishes itself from the sibling ask_pipeworx by emphasizing its experimental nature and current equivalence, making the purpose unambiguous.

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

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

The description provides an explicit usage condition: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the evaluation context (results compared against the stable router). However, it could more explicitly state when NOT to use it (e.g., for stable production routing), though the beta/experimental label implies this.

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 readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: it returns a structured refusal with specific refusal_reason enums, clarifies that it can refuse when data doesn't directly answer, and discloses the extra LLM call cost. It also explains the evidence/verbatim quote behavior, which is critical for high-stakes use. 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 front-loaded with the core value proposition first, followed by return format, refusal conditions, and cost trade-off. Every clause carries functional information, though the return shape list is a bit long. Still, it is structured and scannable, with no filler.

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

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

Given the tool's complexity (refusals, evidence, cost), the description is remarkably complete: it explains success/refusal response shapes, all refusal reasons, and when to prefer the sibling tool. No output schema exists, so the inline return format description is essential and provided. The context signals show rich annotations (readOnly, idempotent), and the description complements them without redundancy.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question', so the schema already provides strong semantic meaning. The description adds that the question is 'in natural language' and that the tool 'fills arguments' internally, which contextualizes the single required parameter. A minor bonus for clarifying the question format, but the schema already covers the aliases.

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 names it a 'hallucination-resistant answer mode' with a specific verb+resource ('EXTRACTS the answer using ONLY what the tool result contains'). It clearly distinguishes from sibling ask_pipeworx by highlighting the grounded/evidence-based nature and refusal behavior. The high-stakes read context further clarifies its unique role.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. Also states when not to use: 'prefer ask_pipeworx for casual lookups' and mentions extra cost trade-off, effectively naming the 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 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 indicate read-only and non-destructive behavior, but the description adds extensive behavioral detail: it decomposes questions, routes to 5,462 tools in parallel, returns gaps[] for unanswered facets, includes contradictions[] for standard/thorough, adds hop and citation_uri fields, semantically excerpts large records, and discloses latency ranges (15-60s, up to 90s for thorough). This goes far beyond the structured annotations.

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

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

The description is long but front-loaded with critical prerequisites (account, alternative tool) and every sentence adds substantive information about behavior, output, or usage. It could be better structured with bullets, but the density is justified given the tool's complexity.

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

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

Despite no output schema, the description fully details the findings packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers account tiers, latency, source types, and limitations for non-structured topics, making it exceptionally complete for a complex tool.

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

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

Schema already covers the two parameters with 100% coverage, so baseline is 3. The description adds meaningful context: the question parameter is meant for natural language, broad/multi-part questions ('decomposition is the point'), and the depth parameter is linked to payment tier ('thorough needs a paid plan'). These additions enhance the schema's descriptions.

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

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

The description clearly states a specific action: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' with a defined scope and mechanism (decomposition + parallel routing). It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and current news, and by noting 'this is NOT open-web search.'

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also notes the paid plan requirement for 'thorough' depth.

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 indicate read-only, open-world, idempotent, non-destructive. The description adds meaningful behavioral context: fans out across multiple sources in one parallel call, soft-fails for USPTO (sunset May 2025), uses GDELT→GNews fallback, and lists exact return sections. This goes well beyond annotations and sets expectations for reliability and behavior.

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

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

The description is dense but well-structured, front-loading example user queries and ending with input constraints. Every sentence contributes: purpose, usage preference, return contents, fallback behavior, and input format. It is appropriately sized for a complex tool without fluff.

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

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

For a complex tool with no output schema, the description explains all major return sections (CIK, filings, fundamentals, patents, news, LEI) and provides operational notes (parallel call, soft-fail, fallback). It covers input, behavior, and limitations sufficiently for an agent to decide and invoke correctly.

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

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

Schema already has 100% parameter descriptions. The description adds value with concrete examples ('AAPL' or zero-padded CIK '0000320193'), reiterates the zero-padding requirement, and clarifies the 'type' parameter's current limitation (only 'company'). That's beyond schema, though not dramatically.

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: building a full cross-source profile of a US public company in one parallel call. It uses a specific verb ('profile'), names the resource ('US public company'), and differentiates from siblings by explicitly recommending it over chaining single-pack SEC/XBRL/news lookups.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion and alternative: names not supported, use resolve_entity first. These are concrete usage rules beyond what schema provides.

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?

Despite having readOnlyHint, openWorldHint, and idempotentHint annotations, the description adds extensive behavioral detail: it explains the compatibility_warning with two distinct trigger conditions, temporal_alignment semantics, and skipped_cross_type/subtype counters. This goes far beyond the annotations and provides essential context for interpreting results. No contradictions with annotations.

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

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

The description is long but well-structured with clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. Every major detail (safety warnings, temporal alignment, skip counters) serves a purpose for a complex tool. It could be trimmed slightly, but the density of valuable information justifies the length.

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

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

With no output schema, the description fully specifies the response structure: leg-by-leg prices, matched spread, top_spreads_pp, compatibility_warning conditions, temporal_alignment fields, and skipped-counters. It also explains the meaning of 'aligned:false' and when spreads are meaningless. This is exceptionally complete for a tool with no structured output definition.

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

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

Schema coverage is 100% with descriptions for all three parameters. The tool description enhances this by explaining the interaction between topic and explicit overrides ('Overrides the topic-mapped... side'), and by listing the concrete shortcut values. It adds meaningful context about mode selection and how parameters combine, though the schema already covers the individual parameter meanings.

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

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

The description starts with a specific verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly states what the tool computes and distinguishes it from sibling tools like polymarket_arbitrage by focusing on cross-venue spread rather than single-venue arbitrage. The two-mode explanation further clarifies scope.

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

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

The description provides clear context: it explains the two modes (pre-mapped topic shortcuts vs explicit tickers) and gives expectations ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'). However, it does not explicitly name alternative tools for comparison or state when to use this tool instead of siblings, only implies its specific use case.

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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: it specifies the returned fields (ticker, CIK, company_name, RxCUI, etc.), mentions citation URIs, explains auto-disambiguation, and notes internal cascading through endpoints. This gives the agent a clear picture of the tool's behavior and outputs.

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 with clear sections for examples, supported types, and return details. It is somewhat long but every sentence adds value. The front-loaded examples make the purpose immediately clear. A slight trim could improve conciseness, but overall it is efficient.

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

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

Given the tool's complexity (two entity types, multiple input formats, different outputs) and lack of an output schema, the description is remarkably complete. It covers return values, citation URIs, and resolution behavior for both company and drug types. It also frames the tool as a replacement for multiple manual lookups, ensuring the agent understands its full role.

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

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

Schema coverage is 100% with parameter descriptions already present. The description further enriches parameter semantics by explaining what each type returns, giving example inputs, and noting auto-disambiguation behavior. For instance, it clarifies that 'company' accepts ticker, CIK, or name and returns a 10-digit CIK from SEC EDGAR, which is not fully captured 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 clearly states the tool's purpose: resolving a user-spoken name to a canonical identifier. It provides concrete example queries and explicitly states 'Use FIRST whenever you have a name but need an ID,' distinguishing it from sibling tools that consume IDs. The verb 'resolve' combined with the resource (entity name) is specific and unambiguous.

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

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

The description gives an explicit usage rule: 'Use FIRST whenever you have a name but need an ID.' This tells the agent exactly when to invoke this tool. It also explains that it replaces 2-3 manual lookups, clarifying its role compared to alternatives. While it doesn't name sibling tools, the guidance is sufficient for correct 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?

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?

Beyond the read-only, idempotent, non-destructive annotations, the description discloses the two execution paths (SEC EDGAR fast path vs grounded pipeline), the percent-delta math, the verdict types, the citation format, and the automatic fallback behavior. This is rich behavioral detail that helps the agent anticipate how the tool operates and what it returns.

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

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

The description is front-loaded with trigger phrases and a concise purpose statement, followed by compact elaboration of paths, output, and value. Every sentence contributes unique information without redundancy or filler, making it appropriately sized for the tool's complexity.

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

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

Despite having no output schema, the description fully specifies the return structure (verdict types, actual value with pipeworx:// citation, reasoning) and covers the two execution paths. It provides examples, explains the fallback, and clearly states the tool's role relative to sequential alternatives, making it complete for a two-parameter 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 provides 100% coverage for both parameters (claim and tolerance_pct), so the description is not required to explain them. It adds context through example claims and refers to tolerance implications, but it doesn't provide additional parameter-level semantics beyond the schema.

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

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

The description clearly defines the tool as a natural-language claim verification tool with explicit trigger phrases and verbs like 'verify', 'confirm or refute', and 'fact check'. It distinguishes itself from sibling research/query tools by focusing on factual claim checking against authoritative sources, with a specific fast path for financial claims and a fallback for other claims.

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 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear when-to-use guidance. It also describes the internal routing between financial and other claims and mentions it replaces 4–6 sequential calls, but it does not explicitly name alternative tools or provide when-not-to-use scenarios.

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