Mhw

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral context: default model, free vs. BYO key cost implications, and that `_apiKey` passes straight through to api.anthropic.com. Does not contradict annotations. Lacks rate limits or latency, but annotations lower the bar.

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

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

Three sentences, each earning its place: what it does, how to configure, return structure, and use cases. No fluff, front-loaded with the core purpose. Perfectly concise for the complexity.

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

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

Given no output schema, the description explains the return shape (per-model {score, confidence, signals, raw_response} + combined view), which is essential. It also covers default behavior and cost. Missing details like what 'signals' means or limitations of the two models, but for a read-only, idempotent tool this is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying the default model ('free'), the payment implication for `_apiKey` ('you pay Anthropic directly'), and that omitting `models` uses only workers-ai. This enriches parameter understanding without duplicating 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 ('probe') and resource ('LLMs'), clearly stating it scores visibility (0-100) per model. It distinguishes itself from siblings like ask_pipeworx (Q&A) or compare_entities by focusing on AI visibility audits, even without explicit sibling comparisons.

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

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

Provides clear context for when to use the tool ('USEFUL for AI-marketing audits, pre-launch brand checks, competitive monitoring'), but lacks explicit exclusions or mention of alternatives. The non-exhaustive usage list gives a strong sense of applicability, though not as prescriptive as 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 destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it works on 'every tier', is 'one fast call', and routes across 5,635 tools. It also discloses that it is the default entry point and handles live news. This goes beyond the annotations in explaining how the tool behaves.

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?

Though lengthy, every sentence is purposeful. The structure is front-loaded with the primary directive and usage triggers, followed by examples and escalation paths. The 'START HERE' and 'Step up only when needed' framing makes the hierarchy clear. No filler content.

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

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

For a meta-tool that routes to thousands of sources, the description is remarkably complete. It covers scope, use cases, examples, alternatives, and limitations. It even notes what it returns (structured answer with citation URIs). Given the tool's complexity, nothing essential for an agent to decide when and how to invoke it is missing.

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

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

Schema coverage is 100% and the schema already documents the 'question' parameter with all aliases (q, text, input, query, prompt). The description reinforces that the parameter is a natural-language question but adds no new syntax or format details. Baseline 3 is appropriate since the schema fully documents the parameters.

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

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

The description begins with a clear directive: 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates specific domains (SEC filings, FDA drug data, FRED/BLS, etc.). It clearly states the tool's function: routes the question to the right tool among 5,635, fills arguments, and returns structured answers with citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs when to use this tool over web search, provides trigger phrases ('what is', 'look up', etc.), and gives concrete examples. It also states when NOT to use it and alternatives: 'Step up only when needed: for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. This is model-example guidance.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint false), so the description doesn't need to restate those. It adds valuable behavioral context beyond annotations: it's a beta with candidate routing, currently identical to ask_pipeworx (since the last candidate retired on 2026-07-26), and it is a full working router—'Falls back to nothing—this IS a full working router, just the experimental edge.' This transparency helps the agent understand potential variability and trust it as functional. The only minor gap is lack of detail on what might change with a candidate active, but that's acknowledged as transient.

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 informative but slightly verbose. It efficiently front-loads the core purpose ('Beta version of ask_pipeworx') and comparison to the stable version, then adds necessary context about current status and usage. Each sentence carries weight, though a tighter phrasing could cut redundancy (e.g., 'identical universal router' + 'same 5,635 tools' is a bit repetitive). Overall, it's well-structured and not bloated.

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

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

For a complex router tool with no output schema, the description covers the essentials: it's functional, how to use it (like ask_pipeworx), its beta status, and that it's currently identical to stable. It doesn't detail the response shape, but it references 'same response shape' as ask_pipeworx, which the agent can look up. It also clarifies fallback behavior. Minor omission: no mention of potential differences in latency or error modes, but given the annotations and schema richness, these are not critical. Overall, it's sufficient for an agent to call it correctly.

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

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

Schema coverage is 100%—the question parameter and all five aliases are fully documented in the input schema. The description adds no parameter-specific information, which is acceptable since the schema already covers semantics thoroughly. Per the rubric, the baseline is 3 when coverage is high, and the description doesn't need to compensate.

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

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

The description clearly states the tool's purpose: it is a beta version of the ask_pipeworx universal router with the same 5,635 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. An agent can immediately understand what it does and how it differs from its sibling.

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 it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router for comparison. It also explains that results are compared against the stable router to decide what merges, clarifying the experimental nature. The alternative (ask_pipeworx) is named directly, leaving no ambiguity.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds behavioral detail: it extracts answers strictly from tool results (preventing hallucination), returns a structured success response with evidence and confidence, explicitly returns refusal reasons on failure, and incurs an extra LLM call. This goes beyond the annotations and fully discloses 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-organized: it opens with the core purpose, then details the process, return format, use cases, and cost trade-off, each sentence earning its place. Slightly long but justified given the complexity and need to differentiate from the sibling.

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 specifies the success and failure return shapes, refusal reasons, and indicates the routing over 5,635 tools. It covers required usage context and cost considerations, leaving no significant gaps for an agent to call it correctly.

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

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

Schema coverage is 100%, with all parameters being aliases for 'question' and the schema describes 'question' as natural language input. The description mentions the question indirectly via 'picks the right tool... fetches the data' but doesn't add specific parameter semantics beyond what the schema already provides. Baseline 3 is appropriate for full 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?

Clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, explicitly contrasting with the sibling ask_pipeworx by emphasizing extraction solely from tool results and refusal behavior. The description names the specific process (routing, fetching, extracting) and distinguishes it from casual lookups, making its purpose unambiguous.

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

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

Explicitly states when to use this tool (answers that will be quoted, cited, or acted on, especially in high-stakes domains like financial, legal, medical, or public statements) and when not to (casual lookups prefer ask_pipeworx due to cost). Also notes the cost trade-off and provides refusal reasons, giving clear guidance on 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 mark the tool readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: resolver match-confidence contract, low-confidence short-circuit behavior, closed-market statuses, fallback news fields, and resolution-rule cancellation risks. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.) and front-loads the core action. It earns its length for a complex fan-out tool, though it could be trimmed without losing essential guidance.

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

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

With no output schema, the description is responsible for explaining return values and it does so comprehensively: result.market, result.analysis, result.evidence, parent_event, statuses, and tradeability flags. It also covers edge cases like low-confidence matches, closed markets, and cancellation rules.

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% (all three params have detailed descriptions). The prose reinforces accepted formats and fan-out behavior but doesn't add meaning beyond the schema, so the baseline 3 applies.

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

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

Description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It details accepted inputs, classification, fan-out, and output, making the purpose unmistakable. It doesn't explicitly contrast with sibling tools, so it gets 4 rather than 5.

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

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

Explicit use-for cases are given: 'should I bet on X', 'what does the data say about Y', 'or is there edge in Z'. However, no when-not-to-use guidance or named alternatives among siblings are provided, so it stops short of a 5.

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

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

Annotations already provide readOnly/idempotent hints, but the description adds rich behavioral details: specifics about data sources (SEC EDGAR/XBRL for company, FAERS for drug), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. No contradiction with annotations; it complements them.

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

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

The description is dense but well-organized, starting with user triggers, then the core purpose, then data-source details, and ending with efficiency benefits. Every sentence provides useful information with no fluff, striking a good balance between detail and brevity.

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 return values (paired data, citation URIs), sorting behavior, and domain-specific caveats. It addresses edge cases like off-calendar fiscal years and clearly communicates the efficiency gain, making it complete for a comparison tool.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'values'. The description adds context by explaining what each type pulls (e.g., 'latest 10-K revenue + net income' for company) and gives concrete examples like tickers and drug brand names, exceeding the baseline but not fully replacing schema documentation.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one call, with specific example triggers like 'X vs Y' and 'which is bigger'. It distinguishes from sibling tools like entity_profile by emphasizing parallel comparison over sequential 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?

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it 'Replaces 8-15 sequential lookups'. This provides clear when-to-use guidance and implies alternatives, aligning with the sibling list where entity_profile likely handles single entities.

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

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

Annotations already set readOnlyHint/openWorldHint/idempotentHint/destructiveHint, and the description adds substantial context beyond them: auth prerequisites (free vs paid tier for 'thorough'), latency expectations (15-60s, up to ~90s), the never-invents policy (explicit gaps[]), citation fetchability semantics (citation_uri only present when resolvable), and the hop/contradiction behavior per depth. Clearly no contradiction with annotations.

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

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

The description is long (~330 words) but front-loaded with the most critical operational fact (account/failover) and every sentence earns its place — failover routing, differentiation from open-web, return packet structure, latency, depth behaviors, citation semantics, excerpting. It is dense rather than padded, though an agent must parse a sizable block; slightly trimmed phrasing could move it to 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 highly complex tool with no output schema, the description is exceptionally complete: it covers prerequisites, return format (findings packet with evidence+confidence+source+fetched_at+fixable citation), failure mode (gaps[]), depth differences, latency, and source scope. An agent has everything needed to call this correctly and interpret results without an output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value beyond the schema by elaborating the practical consequences of each depth enum (re-angles unanswered gaps for 'standard', chases leads and needs a paid plan for 'thorough', 3 vs 6 facets). For 'question' it clarifies that broad/multi-part is encouraged. This nudges the score above baseline without fully compensating for the enum details already present in the schema.

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

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

The description names a specific verb-resource pairing ('Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources') and immediately negates the most likely confusion ('this is NOT open-web search'). It explicitly differentiates from sibling ask_pipeworx by use case, making tool selection unambiguous without opening schemas.

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

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

The description gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'), and post-login failover guidance ('If you are not signed in, use ask_pipeworx instead'). It even names a competing sibling for news topics with a behavioral reason (structured catalog yields empty gaps[]). This is textbook usage routing.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds concrete return behavior: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are ready to call directly. This extends beyond annotations without contradiction.

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

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

Three sentences cover purpose, scope/return value, and usage guidance. The domain list is somewhat lengthy but serves as a quick reference for the agent. No redundant 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?

Despite no output schema, the description fully explains what the tool returns (top-N matching tools with complete schemas) and how to use it effectively. It also mentions the direct-call capability, making it self-sufficient for an agent.

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

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

Schema coverage is 100%, with all parameters (query, q, task, limit, search, description) documented including aliases and defaults. The description adds no parameter-level detail beyond what the schema already provides, so baseline 3 applies.

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

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

The description opens with 'Find tools by describing the data or task' – a specific verb and resource that clearly defines the tool's meta-purpose. It further distinguishes from siblings by positioning itself as a tool-discovery mechanism rather than a domain-specific tool, and lists supported 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?

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. This clearly states when to use it and implicitly when not to (when a single answer is already known).

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

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

Annotations declare readOnly/idempotent/openWorld, and the description adds substantial behavior beyond that: it fans out across multiple sources in parallel, returns specific structured fields, includes a soft-fail for the USPTO API sunset, and describes a GDELT→GNews fallback. 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 dense, front-loading purpose and usage, then listing return fields and input constraints. Every sentence adds distinct value, though it could be trimmed slightly; the length is justified by the tool's complexity.

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

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

With no output schema, the description fully enumerates return components (cik, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI) and covers input edge cases. It also notes the parallel-call implementation, leaving no major gaps for an agent.

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

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

Schema description coverage is 100%, with both 'type' and 'value' fully documented including examples and the name restriction. The description's parameter guidance ('Pass ticker AAPL or zero-padded CIK...') essentially mirrors the schema, adding no new semantic information, 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 concrete example queries and states 'full cross-source profile of a US public company in ONE parallel call', clearly identifying the verb (profile) and resource (US public company). It distinguishes from siblings by explicitly preferring this over chaining single-pack lookups and pointing to resolve_entity for name-based input.

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

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

It gives explicit usage context: use when the user wants a holistic view ('Tell me about X', 'research Acme', etc.), and explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It also provides an exclusion: 'names not supported (use resolve_entity first if you only have a name)'.

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 signal destructive behavior (destructiveHint: true) and idempotency (idempotentHint: true). The description adds context about clearing sensitive data and deleting by key but does not go beyond what annotations provide. No contradiction.

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

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

Two concise sentences, front-loaded with the action and followed by usage guidance. Every sentence adds value with 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 single-parameter delete tool with annotations covering destructive behavior, the description plus schema is largely complete. It could mention return behavior or failure handling, but the low complexity makes this a minor 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% with a clear description of the 'key' parameter. The description only repeats that the key identifies the memory, adding no extra syntax or 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 uses a specific verb ('Delete') and resource ('previously stored memory by key'), clearly distinguishing it from siblings like remember and recall. It states exactly 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?

Explicitly describes when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also references related tools ('Pair with remember and recall'), giving the agent clear usage 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses the operational behavior: it fetches the page, extracts title/description/key links, and emits a text blob in llms.txt markdown. This adds meaningful context about the tool's internal process and output format, going beyond what annotations convey.

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

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

The description is well-structured and front-loaded: the first sentence states purpose, the second explains the process and output, and the third lists use cases. Every sentence earns its place, and there is no fluff or redundant content.

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

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

Despite not having an output schema, the description explicitly states the output is a single text blob in standard llms.txt markdown, ready for site-root placement. With only two parameters, one optional, and rich annotations, the description fully covers purpose, process, output, and ideal use cases, making it complete for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage with clear descriptions for both 'url' and 'max_links'. The description reinforces the URL parameter by saying 'any URL' and mentions the output but does not add new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It clearly distinguishes itself from siblings by focusing on llms.txt generation, mentioning the extraction of title/description/key links and emitting standard markdown, which is not covered by sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 with the 'Useful for:' list, covering client indexing, personal project drafting, and competitor auditing. It gives clear context for when to use the tool, though it does not explicitly mention when not to use it or name alternative tools, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the return field types (defense, resistances, slots), which is useful but does not go beyond what the annotations and output schema likely already convey. No contradiction.

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

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

The description is two sentences, front-loaded with the verb and resource, and contains no filler. Every clause adds meaningful information: the action, the scope, and the return data.

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

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

For a simple read-only tool with an output schema and rich annotations, the description is mostly complete. However, the reference to 'rank and type' without corresponding parameters creates a gap that could mislead an agent into assuming filters exist. This reduces completeness.

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 only parameter (limit) with 100% coverage, so the description does not need to add parameter details. However, the description's mention of 'by rank and type' is misleading because no such parameters exist in the schema, potentially confusing the agent.

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

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

The description clearly identifies the resource (Monster Hunter World armor) and the action (find by rank and type), and lists key return data (defense, elemental resistances, skill slots). This differentiates it from sibling tools like get_weapons and get_monsters, which focus on other game entities.

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

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

The description gives clear context for when to use the tool (when needing armor stats for set building), but does not explicitly mention alternatives or exclusions. A score of 4 is appropriate for clear context without explicit when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by disclosing what data is returned (species classification, elements, ailments, weaknesses), which goes beyond the safety annotations. No contradictions exist.

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

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

The description is two sentences, front-loaded with the action and resource, and every clause contributes necessary information. No filler or repetition.

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

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

With a robust schema and rich annotations, the description sufficiently completes the picture by stating the return fields and the planning use case. An output schema exists, so return value details are not needed in the description.

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

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

Schema description coverage is 100% for all four parameters, so the schema fully documents name, type, limit, and species. The description only summarizes these filters without adding new details, thus the baseline of 3 applies.

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

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

The description uses a specific verb ('Search') and identifies the resource ('Monster Hunter World monsters') with clear filter dimensions (name, species, size class). It distinguishes itself from sibling get_* tools by focusing solely on monsters and their stats.

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 the use case ('to plan hunts') and what filters can be applied, providing clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, though the resource distinction makes the intended usage obvious.

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 clear. The description adds return content (descriptions, max ranks, level-by-level effects) but does not disclose additional behavioral traits like pagination behavior or rate limits. It adds moderate value beyond the annotations.

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

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

The description is two concise sentences with no superfluous words. It front-loads the primary action and then provides return details and use case. 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?

The output schema and annotations provide substantial context, so the description need not explain return structure. However, the 'by name' wording creates a gap about how to select a specific skill, which is not resolved by the schema. This missing clarification prevents the description from being fully complete.

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

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

The input schema has one parameter (limit) with 100% coverage, so the baseline is 3. However, the description mentions 'by name', implying a name parameter that does not exist in the schema, which actively misleads an agent about how to invoke the tool. The description should have aligned with the schema or clarified that searching by name is not required.

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 resource (Monster Hunter World skills) and action (look up), distinguishing it from sibling tools like get_armor and get_weapons. However, the claim 'by name' is not supported by the input schema, which only includes a 'limit' parameter, introducing ambiguity.

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

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

The description provides a clear use case ('optimize your build') and implies this tool is for skills specifically, given sibling names. It does not explicitly exclude alternatives or mention when-not-to-use, but the context is sufficient for an agent to make an informed choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns damage, elements, and rarity, but does not disclose any additional behavioral traits such as pagination or default filtering. No contradiction with annotations.

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

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

The description is a single sentence of about 25 words, front-loaded with the verb and resource. It earns its place by mentioning return fields, though the examples are inaccurate.

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 a simple tool with two optional parameters, a fully described schema, and an output schema, the description is largely complete. However, the misleading type examples undermine overall completeness and usability, so it is not a perfect 5.

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

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

The description's examples ('Great Sword', 'Bow', 'Hammer') do not match the schema's enum values ('great-sword', 'bow', 'hammer'), actively misleading parameter usage. While schema coverage is 100%, the incorrect examples provide negative value, so the score falls below the baseline of 3.

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

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

The description clearly states 'Browse Monster Hunter World weapons by type' with a specific verb and resource, and lists example types. It differentiates from sibling tools like get_armor and get_monsters by focusing on weapons.

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

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

The description implies usage for browsing weapons by type, providing clear context about the domain and return fields. It does not explicitly mention when not to use it or point to alternatives, but the context is clear enough for a simple read 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, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds value by specifying the exact return fields (id, type, params, created_at, etc.) and scoping to the caller's active subscriptions, providing useful behavioral context beyond the annotations.

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

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

The description is exactly two sentences, front-loaded with the core purpose and followed by a usage tip. Every word contributes value with no redundancy, making it highly efficient and well-structured.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context. Annotations cover safety semantics, and the schema covers parameter details, leaving no significant gaps in the information needed 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?

The sole parameter include_inactive is fully described in the schema with 100% coverage, so the description need not add parameter details. The description does not mention the parameter at all, but the schema carries the burden, meeting 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 the specific verb 'List' and clearly identifies the resource as 'the caller's active subscriptions.' It also lists the returned fields, making the tool's function unmistakable and distinguishing it from sibling tools like subscribe and unsubscribe which perform mutations.

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

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

The description explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This implicitly references the sibling subscribe and unsubscribe tools, though it does not explicitly name them as alternatives, so it falls just short of a perfect score.

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

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

Beyond the annotations (all false flags), the description discloses substantial behavioral context: the two-phase claim_token flow, 'Rate-limited to 5 per identifier per day,' 'Free; doesn't count against your tool-call quota,' and that 'The team reads digests daily.' No contradiction exists between the description and annotations.

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

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

The description is longer than average (~150 words), but it is front-loaded with the core purpose and every sentence contributes distinct information about use cases, exclusions, token semantics, and operational constraints. Some redundancy with the schema's claim_token description exists, but the structure is logical.

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

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

Despite lacking an output schema, the description explains return behavior ('returns a claim_token,' later 'read whether it was fixed and what changed'). It covers rate limits, quota, exclusions, and parameter usage, making it complete for a feedback tool with 4 optional parameters and a two-step flow.

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 each parameter, so the baseline is 3. The description adds value by advising 'don't paste the end-user's prompt' and explaining how claim_token integrates across two calls, going beyond the schema's static description.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which is a specific verb+resource combination. It clearly differentiates from sibling tools, none of which are feedback-focused, and aligns with the title 'Send Pipeworx Feedback'.

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 a tool returns wrong/stale data (bug)... feature/data_gap... praise.' It also provides a clear exclusion: 'if the tool came from a different MCP server... report it with that server instead,' and offers a decision heuristic for uncertainty ('Not sure? Pipeworx tool names are the ones this connection lists.').

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

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

The description adds valuable context beyond annotations: it mentions caching behavior (5min-1h), no PII, and that it is derived from CF analytics-engine. Annotations already declare readOnly/idempotent, and the description enriches the behavioral picture.

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

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

The description is compact yet information-dense, leading with the core purpose and following with bulleted, practical use cases. Every sentence earns its place, and there is no redundant phrasing.

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

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

For a simple read-only tool with one enum parameter and no output schema, the description fully covers purpose, output concept, caching, privacy, and use cases. Nothing essential is missing given the 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?

Schema description coverage is 100% for the 'window' parameter, which includes enum values and explanatory text. The tool description restates the window but adds no new semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over configurable windows. It distinguishes itself from siblings like discover_tools by focusing on aggregate usage trends rather than listing available 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?

Three explicit use cases are given: discovering hot data sources, confirming canonical tools, and checking alignment with agent demand. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a perfect score.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals rich behavioral details: partition-check logic, >3pp deviation threshold, placeholder filtering with 20% fraction rule, fill-check pricing against live CLOB depth, and the meaning of realizable_edge_pp ≤ 0. It also surfaces skipped_low_similarity and placeholders_filtered in the response, leaving no hidden surprises.

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

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

The description is long but every sentence earns its place. It is front-loaded with purpose and mode selection, then organized with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that make it scannable. Concrete examples and structured response enumeration prevent ambiguity without bloat.

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 fully covers return values (opportunities[], partition_check fields), edge cases (low similarity, placeholder fraction), and error conditions (realizable_edge_pp ≤ 0). It also addresses parameter behavior and limitations comprehensively, making it self-sufficient for an agent to invoke correctly.

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

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

Although the schema already describes both parameters fully (100% coverage), the description adds substantial meaning beyond it: concrete slug examples, what each mode does internally (walks child markets, flattens markets, runs comparator), and how the semantic anchor and partition filter apply. This goes far beyond the schema's basic field descriptions.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no args, event, topic) and explicitly differentiates from siblings by referencing polymarket_fill_risk for custom sizing. This leaves no ambiguity about the tool's core 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?

Provides explicit when-to-use guidance: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also notes what cross-event mode catches that single-event misses, and directs users to polymarket_fill_risk for custom sizing. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond that: it discloses caching behavior (Cached 1h at the KV level), the diagnostics funnel (_diagnostics with filter_skips), the 24h-move warning, and gate details like 'rare-by-design' with relaxed Run 8 parameters. 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 front-loaded with a clear-purpose sentence, then organized into labeled sections: model families, top-level response, knobs, and diagnostics. Every sentence conveys a specific fact—no filler or repetition—making the length appropriate 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?

With no output schema, the description compensates by fully specifying the response top-level structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, spread_pp), and even caching details. Given 9 parameters and three model families, this is a complete, and self-sufficient description.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial meaning: it groups knobs into 'tradeable-edge knobs', explains why min_kelly does not filter partition arbs (parent-level kelly=0 by design), and describes min_partition_leg_kelly as applying to per-leg Kelly inside top_legs. This goes well beyond the individual 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 opens with a specific verb plus resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also enumerates the three response segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its scope unmistakable and distinguishing it from sibling tools like polymarket_arbitrage.

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

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

The phrase 'Built for "what should I bet on today"' gives a clear use case, and the description explains why Fed bets are excluded and when knobs like min_liquidity/max_spread_pp are relevant. It does not explicitly name sibling alternatives or state when not to use this tool, but the context is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc., but the description adds substantial behavioral context: snapshot gaps mean 'nobody scanned that day,' history depth is bounded by a '60-day snapshot TTL,' and decay numbers come from 'daily closes of edge_pp_net (net of default slippage), not intraday.' This explains data freshness and computation nuances that annotations cannot convey. No contradiction.

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

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

Although long, the description is highly structured with labeled segments: purpose, Args, RESPONSE (with tracked[], expired[], snapshot_dates[] and their meanings), and LIMITS. Every sentence carries information; nothing is redundant or filler. The front-loaded purpose and clear section caps make it scannable despite the detail.

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

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

With no output schema, the description fully explains the response shape (tracked[], expired[], snapshot_dates[]), including field semantics (trend, decay_pp_per_day, lifespan_days). It also covers edge cases like snapshot gaps, TTL bounds, and slippage assumptions. The tool is complex (time-series analysis), and nothing important seems missing.

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

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

Schema coverage is 100% with both parameters described ('Lookback in days (default 14, clamp 2-30)' and 'Which polymarket_edges window family...'). The description adds 'snapshot family' context and clarifies days max, but this is marginal. The minor mismatch (description says max 30, schema says clamp 2-30) doesn't add meaningful value beyond schema; 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?

Description opens with 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots'—a specific verb+resource+scope that clearly differentiates from sibling polymarket_edges. It answers a concrete question ('how long has this edge existed and is it shrinking?') and explicitly contrasts fresh vs old edges, making the tool's unique value obvious.

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

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

The description gives strong contextual guidance: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take).' This implies when to use the tool (when edge age matters). It doesn't explicitly name alternatives or exclusions (e.g., 'use polymarket_edges for current edge only'), but the context is clear enough that a 'when not to use' is inferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds substantial context: it walks the order-book ladder, returns specific fields like top_of_book and vwap_fill_price, and warns about forced_directional_risk from partial basket fills. This is exactly the kind of behavior disclosure that helps an agent anticipate side effects and interpret results.

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

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

The description is long but intentionally structured with REQUIRES, SINGLE-MARKET, BASKET, and USE-THIS sections. Every sentence carries essential information about modes, defaults, return fields, or risk. No filler or repetition; the density is justified by the tool's complexity.

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

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

Given there is no output schema, the description fully enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also provides usage context and risk warnings, making it complete for an agent to decide on invocation and interpret responses.

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

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

Although schema coverage is 100%, the description clarifies mode-dependent semantics that the schema alone does not convey. For example, size_usd in single-market mode is 'max spend on buys, target proceeds on sells,' while in basket mode it is 'settlement notional — shares per leg, each paying $1.' It also explains the auto behavior of side in basket mode. This adds real value beyond the structured 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 opens with a precise purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distills the tool's function and distinguishes it from sibling tools by explicitly naming polymarket_arbitrage and polymarket_edges as the tools this one complements. The two modes (single-market and basket) are clearly defined.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround on thin books is not capturable, partial fills create directional risk), which goes well beyond a simple 'when to use' statement.

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

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

The description goes far beyond annotations by detailing specific behavioral traits: compatibility_warning conditions (e.g., matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment semantics, and skipped_cross_type/subtype counters. It also outlines the response structure including leg-by-leg prices and top_spreads_pp. Annotations declare readOnly/openWorld/idempotent/non-destructive, and the description adds deep context without any contradiction. This is exceptional transparency.

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

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

The description is longer than average but every sentence contributes meaningful information about modes, response, or safety fields. It is well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. The density is justified by the tool's complexity, and there is no wasted repetition.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns: leg-by-leg prices, matched spread with top_spreads_pp, and all safety fields including compatibility_warning conditions, temporal_alignment, and skip counters. It also explains the meaning of alignment failures. This is more than sufficient for an agent to invoke the tool and correctly interpret results.

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

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

Schema coverage is 100% with each parameter already described, including override behavior (e.g., 'Overrides the topic-mapped Kalshi side'). The description restates the topic list and groups parameters into two modes, but this adds little beyond the schema. It does provide conceptual clarity around the modes, but since the schema already does the heavy lifting, a baseline 3 is appropriate.

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

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

The description clearly defines the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes (topic shortcuts and explicit tickers). It distinguishes from sibling tools by focusing on this specific venue pair and by explaining that the tool reports compatibility issues when bet shapes differ. This is a specific verb+resource+scope formulation.

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

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

The description explains two modes and when to use each: topic shortcuts for pre-mapped macro events, and explicit tickers for custom pairings. It also includes a critical caveat that most pre-mapped topics return compatibility_warning today, guiding agents toward explicit mode for reliable spreads. However, it does not explicitly name alternative tools (e.g., polymarket_arbitrage) or state when not to use this tool, so it lacks 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds meaningful scoping context ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of retrieving a value vs listing keys. It doesn't contradict annotations.

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

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

The description is three sentences, front-loaded with the core action, and each sentence adds value (action, usage examples, scoping/pairing). No wasted words.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description covers behavior, usage, examples, scoping, and relationship to sibling tools. It is complete enough for an agent to select and invoke correctly.

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

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

The sole parameter `key` is already fully described in the schema ('Memory key to retrieve (omit to list all keys)'), so schema coverage is 100%. The description echoes this same information without adding new parameter semantics, yielding a baseline of 3.

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

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

The description clearly states the tool 'Retrieve a value previously saved via remember, or list all saved keys', using specific verbs and a defined resource (saved memory keys). It distinguishes from siblings by naming `remember` and `forget` as paired tools and specifying the omit-key behavior.

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

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

It explicitly instructs when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch' and gives concrete examples. It also names alternatives/paired tools ('Pair with remember to save, forget to delete'), providing clear selection 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 indicate read-only and idempotent behavior. The description adds valuable nuance beyond annotations: it discloses the mark_read side effect (state change) and describes event payload composition. This is transparent and does not contradict the readOnlyHint, as the primary operation is read-only and the side effect is optional and clearly disclosed.

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 purpose, and every sentence earns its place. The alternative HTTP endpoint is presented compactly without unnecessary detail. Perfectly scoped 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?

The description fully covers the tool's behavior given its moderate complexity (5 optional params, no output schema). It explains the event contents, filtering options, mark_read semantics, polling suitability, and an alternative access method. Rich annotations further round out the context, making it complete.

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

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

Schema coverage is 100% and each parameter has a description. The description adds extra meaning by explaining how type and since combine ('filter by type and/or since'), providing a concrete type example ('sec_8k'), and clarifying the purpose of mark_read (so the next call only shows newer ones). This elevates it above the baseline.

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

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

The description clearly states the tool pulls fired events from the subscription feed, with a specific verb and resource ('Pull fired events'). It uniquely distinguishes itself from siblings like list_subscriptions by focusing on alert retrieval from the persisted feed, and it adds useful context about event structure (source, citation_uri, raw payload).

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

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

The description provides clear context on when to use the tool (for polling fired alerts) and offers an explicit alternative (the direct HTTP endpoint for scripts/dashboards). However, it does not explicitly contrast with sibling tools or mention when not to use it, so it falls short of full 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?

With annotations already declaring read-only, open-world, idempotent, and non-destructive behavior, the description adds valuable operational context: it fans out to multiple APIs in one parallel call, details fallback behavior, and mentions the PatentsView sunset. This goes beyond the annotation baselines.

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

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

The description is dense but well-organized, starting with user-intent examples and moving through the data sources, parameters, and return format. It's longer than average but every sentence carries meaning; still, a bit more compression would be possible.

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 explains the return value structure (changes[] grouped by source, total_changes, citation URIs). It also covers the multi-source fan-out and failure modes, making it fairly complete for a complex tool. Missing granular detail on the shape of each change item, but acceptable.

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 at 100% detail. The description enriches this by explaining the accepted formats for `since` (ISO or relative shorthand) and recommending "30d" or "1m" for typical monitoring, which adds practical guidance beyond the schema listings.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, with explicit examples of natural language queries. It also distinguishes itself from the sibling tool entity_profile by directing users to that alternative for static profiles.

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 via query examples and even recommends a fallback tool (entity_profile) for static profiles. It also details the internal fallback logic between data sources (GDELT to GNews) and notes the USPTO soft-fail condition, giving clear context for trade-offs.

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

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

Annotations already cover the non-read-only, idempotent, non-destructive nature. The description adds valuable context: key-value storage scoped by identifier, and persistence differences between authenticated (persistent) vs anonymous (24-hour) sessions, which is not disclosed by annotations. It does not contradict annotations, though it omits explicit overwrite semantics.

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 core action, when to use it, and persistence details alongside sibling references. No filler, no redundancy, and the main purpose is front-loaded.

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

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

For a simple two-parameter storage tool with no output schema, the description covers the use case, storage semantics, authentication implications, and relationship to recall/forget. It is complete enough for an agent to select and invoke the tool correctly without further context.

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

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

The input schema fully describes both parameters with 100% coverage. The description enhances this by explaining the overall purpose ('data the agent will need to reuse later') and the storage model ('key-value pair scoped by your identifier'), giving semantic meaning to how key and value relate. This contextualization goes beyond the schema's simple field 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 clearly states the tool saves data for reuse, using the specific verb 'Save' and a defined resource ('data the agent will need to reuse later'). It distinguishes itself from sibling tools by explicitly pairing with recall for retrieval and forget for deletion, establishing it as the memory-writing tool.

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 says exactly when to use the tool: 'Use when you discover something worth carrying forward' with concrete examples like resolved tickers and preferences, and gives clear alternatives ('Pair with recall to retrieve later, forget to delete'). This provides explicit guidance for choosing among related tools.

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

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

The description discloses key behaviors beyond the annotations: internal cascading through multiple lookup endpoints ('using resolve_entity replaces 2-3 manual lookups'), graceful degradation if external services are unavailable ('EDGAR identifiers still return'), and the output structure (identifiers with source labels and an 'unresolved' array). This aligns with and supplements the annotations (readOnlyHint, openWorldHint, idempotentHint) 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 front-loaded with example queries and a clear purpose statement, followed by structured details for each entity type. While it is somewhat lengthy, every section adds value and the organization is logical. It earns a high score for structure but loses a point due to slight verbosity in the entity type explanations.

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 identifier sources, graceful degradation), the description is comprehensive. It covers input options, internal behavior, output expectations, and failure modes. However, it does not explicitly differentiate from the sibling 'entity_profile' tool, and the absence of an output schema means the description must carry the full burden of explaining return values, which it does adequately.

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 descriptions for both parameters (type and value) with 100% coverage. The description reinforces these meanings through example queries and elaboration on identifier resolution, but does not add substantial new semantic information beyond what the schema already offers. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It provides specific example queries and explicitly lists the supported entity types ('company' and 'drug'), making the tool's function immediately understandable and distinct from siblings like 'entity_profile' or 'compare_entities'.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details when to use the 'company' type (e.g., with ticker, CIK, ISIN, or company name) versus the 'drug' type, and explains the resolution behavior across multiple data sources. This clarity helps the agent select the tool correctly.

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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful process details: that it probes each entity through ai_visibility_check, ranks by score, and surfaces most/least recognized. It also mentions the return structure (score, confidence, signal density), which is not in any output schema. This adds value beyond annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the primary action ('Compare AI visibility across multiple entities side-by-side'), followed by the mechanism and use case. Every sentence contributes meaningful information without redundancy or fluff.

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

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

For a tool with 4 parameters, 100% schema coverage, and no output schema, the description provides adequate context: it explains the multi-entity probe behavior, ranking, and return fields. It also gives a practical example. It does not mention potential latency or external API costs from probing multiple entities, but the annotations (openWorldHint) and schema cover the technical details. Overall it is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The tool description does not add parameter-specific meaning beyond the schema; it restates the overall purpose and gives a use-case example, but the schema already describes 'entities', 'models', '_apiKey', and 'context' in detail. No new semantic info about parameters is provided.

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 core function: 'Compare AI visibility across multiple entities side-by-side.' It specifies a verb (compare), a resource (AI visibility), and differentiates from siblings by explicitly mentioning it probes with 'ai_visibility_check' and ranks results, which is distinct from a single-entity check.

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

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

The description provides explicit use cases ('competitive AI-marketing audits') and a concrete example ('does Claude know about us as well as our competitors?'). It also references the underlying single-entity tool 'ai_visibility_check', implying an alternative. However, it does not explicitly state when not to use this tool or contrast it with 'compare_entities', 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 indicate read-only, idempotent, and non-destructive behavior, but the description adds valuable nuance: it explains partial failures degrade gracefully, that the first bundlephobia measurement can take 5-30 seconds, and that sources_failed will list timeouts. These details are not present in annotations and help the agent set expectations.

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

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

The description is a tightly structured four-sentence paragraph that front-loads the purpose, then covers usage, output fields, and caveats. Each sentence earns its place, and the information is dense 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 composite tool with no output schema, the description compensates by listing the exact summary block fields, mentioning per-advisory details, links, and alternative versions, and noting edge cases like bundlephobia timeouts and ecosystem scoping. This gives the agent enough context to use the tool correctly.

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

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

The input schema already provides 100% coverage for both parameters (package and version). The description confirms defaults and scoped package acceptance but does not add new semantic details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite 'should I add this npm package to my project' check, naming the exact sources (deps.dev, bundlephobia) and the type of output. It also distinguishes from siblings by explicitly scoping to the NPM ecosystem in v1 and mentioning alternative routes for other ecosystems.

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 direct usage triggers: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also explicitly directs non-NPM users to 'deps.dev:version directly', providing clear when-to-use versus alternative guidance.

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

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

Beyond the annotations (read-only, idempotent), the description discloses specific algorithmic details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows' and 'cap is 200K chars (longer inputs are truncated and flagged).' It also tells the agent that offsets enable verification of verbatim quotes.

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 every sentence adds distinct value—usage context, algorithm details, and integration with another tool. It is dense but not wasteful.

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 covers the return format ('top-N passages with character offsets and similarity scores') and important constraints (cap, truncation). It also explains the workflow with ask_pipeworx_grounded, making it complete for an agent to select and invoke correctly.

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

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

The schema already describes all three parameters fully (text, query, limit) with good detail. The description adds context about the algorithm and use case but does not materially enrich understanding of individual 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 performs 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from siblings by explaining that it pairs with ask_pipeworx_grounded for grounding over passages 'instead of the whole document.'

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

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

It explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also provides an alternative workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.'

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

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

The description reveals substantial behavioral detail beyond the annotations: persistence requirements (OAuth-only, anonymous/BYO cannot persist), phone verification and 10/day SMS cap, webhook HMAC signing secret returned once, and auto-disabling after 10 consecutive failing runs. These are critical operational behaviors that annotations do not convey.

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

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

The description is dense and well-structured, with the core purpose in the first sentence and supporting details following. While it is a long paragraph, every sentence carries useful information; it could benefit from bullet points but remains appropriately scannable.

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 nested parameters and no output schema, the description covers all necessary context: what it does, return value, auth prerequisites, supported types with parameter formats, delivery channels, and failure behaviors. No critical gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful examples for each type (sec_8k, polymarket_edge, fred_series) and clarifies delivery channel nuances (phone must match verified account, webhook signing secret). This goes beyond the schema's terse field descriptions.

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

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

The description uses a specific verb ('Create') and names the resource ('proactive monitoring subscription to a live-data event stream'), immediately distinguishing it from sibling tools like list_subscriptions, unsubscribe, and recent_alerts. It also states the return value (subscription id), which reinforces its create-oriented purpose.

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

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

The description provides clear context for use, including required authentication (Pipeworx OAuth account), supported subscription types with examples, and delivery channel options. It does not explicitly mention when to prefer this over siblings, but it is self-evident that it is for creating subscriptions, and no exclusions are needed beyond the noted auth requirement.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context that results are drawn from a 'live catalog of thousands of tools' and that it returns example questions (not full answers), setting appropriate expectations for the output. 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 somewhat long, but it is well-structured: it begins with trigger phrases, then states the tool's purpose, return content, usage options, and when to use it. Every section adds necessary information, though the initial example query list could be trimmed without losing core 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?

Since there is no output schema, the description correctly explains that the tool returns category-bucketed example questions with tool and argument shapes. It also covers the optional parameter and when to use the tool, making it sufficiently complete for an agent to invoke it appropriately.

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 a full description of the `topic` parameter (100% coverage), including allowed values and the default behavior when omitted. The description's mention of example topics like 'finance' or 'pharma' adds marginal clarity but does not provide substantive new semantics beyond the schema.

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

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

The description clearly states this is an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape, making it easy to understand what the tool does. It is well-differentiated from siblings like discover_tools by focusing on generating query ideas rather than just listing 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 usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains how to call it with or without a topic. It does not explicitly say when not to use it, but the 'use first' phrasing implies precedence over other tools.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=true), the description discloses that ownership is enforced, the row is deactivated rather than deleted, and historical events remain accessible. This adds valuable context about side effects and data persistence.

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

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

Two sentences, front-loaded with the action, and every sentence adds value: the first states the operation, the second explains ownership and non-deletion behavior. 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 1-parameter tool with no output schema, the description covers the core behavior, constraints, and data persistence implications. It could mention the response or error case but is not necessary for basic usage.

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

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

Schema coverage is 100% and the id parameter is already described as 'returned by subscribe.' The description adds no new meaning beyond 'by id,' so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Cancel a subscription by id.' This uses a specific verb (cancel) and resource (subscription), and the ownership detail distinguishes it from sibling tools like list_subscriptions or subscribe.

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

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

The description provides clear context on when to use this tool (to cancel a subscription you own) and implies limitations (only your own subscriptions). It also mentions subsequent access to historical data via recent_alerts, but it doesn't explicitly name alternatives or exclusion criteria.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description reveals two routing paths (SEC EDGAR/XBRL vs grounded pipeline), the full verdict set, and the critical semantics of could_not_verify (not evidence) and unsupported (no source found). It also discloses that could_not_verify carries a structured verification_error. This is rich behavioral context with no contradiction to annotations.

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

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

The description is dense but well-organized: example queries, routing, verdict list, and an IMPORTANT caller warning. Each sentence adds value, though the opening example list is somewhat long. Not as tight as a two-sentence high-efficiency description, but justified by the tool's complexity.

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

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

With no output schema, the description fully specifies expected return values: the verdict enum, the grounded/structured value with citation, reasoning, and verification_error details. It also covers edge cases (could_not_verify vs unsupported) and usage context, making the tool usage complete for an agent.

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

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

Schema parameter descriptions are comprehensive (100% coverage) for claim and tolerance_pct, including defaults and override guidance. The tool description adds minimal param-specific info beyond reinforcing that claim is natural language and referencing exact percent-delta math. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it validates natural-language factual claims, with explicit example queries. It distinguishes itself from siblings by noting it replaces a 4–6 step pipeline and handles both structured SEC EDGAR and grounded fallback paths.

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 when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also implies alternatives by explaining it replaces sequential calls, but does not name specific sibling tools or explicitly state when not to use it.

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