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 establish that the tool is read-only, idempotent, and open-world. The description adds useful behavioral context: it routes questions to a large tool ecosystem, fills arguments on the user's behalf, and returns answers with stable pipeworx:// citation URIs. It does not discuss rate limits, error behavior, or output shape, but the core call behavior is transparent.

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 useful 'PREFER OVER WEB SEARCH' guidance, but it is far too long and contains duplicated content: the same example list and 'START HERE for most questions' sentence appear twice. It also ends with a garbled, hard-to-parse clause about news feeds, adding noise rather than value.

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

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

Given no output schema, the description appropriately discloses that the result is a structured answer with citation URIs. It also explains what kinds of questions qualify, gives concrete examples, and tells the agent to start here for most factual queries. The main gap is the lack of clarification relative to the ask_pipeworx_beta and ask_pipeworx_grounded siblings, and the redundant phrasing that obscures key guidance.

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

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

Schema description coverage is 100%, so the schema already explains the six alias parameters and the main 'question' parameter. The description enriches the parameter semantics by showing natural-language question examples and broad factual domains, but it does not add meaningful format or syntax details 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 identifies the tool as a natural-language question router that dispatches to thousands of verified sources and returns structured answers with citations. It also contrasts itself with web search. However, it does not explicitly differentiate itself from the closely named siblings ask_pipeworx_beta and ask_pipeworx_grounded, so it falls just short of a 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?

The description gives explicit trigger conditions with starter phrases such as 'what is', 'look up', 'find', 'get the latest', and 'how much', plus a clear 'START HERE' preference rule and domain examples. It names web search as an alternative to prefer it over, but it does not provide when-not-to-use guidance or routing guidance among the ask_pipeworx variants.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context beyond that: candidate routing improvements may be live, none are active as of 2026-07-26, results are compared against the stable router, and it falls back to nothing—it is a full working router. This is strong behavioral transparency about an experimental edge.

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 beta identity and then current state, usage, and fallback. Each sentence earns its place. It is slightly verbose with repeated 'same ... same ... same' phrasing, but remains well structured.

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

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

For a complex universal router with no output schema, the description is quite complete: it ties the response shape and arguments to ask_pipeworx, explains live candidate status, and explicitly states it is fully functional. It relies on the agent knowing ask_pipeworx semantics, but that is reasonable given the sibling context and explicit sameness statement.

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

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

Schema description coverage is 100%, so the schema already documents parameters. The description adds that the tool takes the same arguments as ask_pipeworx, which is useful cross-reference information, but it does not need to repeat parameter details. 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?

States a specific verb-resource relationship: it is the beta version of ask_pipeworx, an identical universal router with 5,798 tools and the same arguments/response shape. It distinguishes itself from the stable ask_pipeworx and the experimental edge is named explicitly. An agent can tell exactly what this tool is for.

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

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

Explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and clarifies that no candidate is currently active so it matches ask_pipeworx exactly. This is clear guidance for the stable-vs-beta choice. It does not mention the grounded sibling alternative, but it does enough.

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

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

Annotations already declare the tool read-only and non-destructive, and the description adds valuable behavioral detail beyond that: it returns an evidence verbatim quote, may return explicit refusal reasons including 'not_in_source' and 'data_truncated,' and costs an extra LLM call. The 'ONLY what the tool result contains' clause sets clear factual-grounding expectations. There is no contradiction with the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, output contract, refusal behavior, usage guidance, and cost tradeoff are all covered without fluff. The key distinguishing trait, 'grounded' / hallucination-resistant, is front-loaded in the first sentence.

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 compensates by specifying the success return shape, refusal shape, refusal reasons, and evidence-quote behavior. It also covers when to prefer this over the sibling and what tradeoff to expect. An agent has everything needed to decide when to invoke it and what to expect back.

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

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

Schema description coverage is 100%, and the parameter schema already fully documents the natural-language question plus its aliases. The description does not add parameter-specific meaning, but it doesn't need to because the schema carries that weight. The baseline of 3 is appropriate here.

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 a specific capability: a hallucination-resistant answer mode that routes to the right underlying tool, fetches data, and extracts answers only from tool results. It also distinguishes itself from the sibling ask_pipeworx by highlighting the grounding behavior and the extra LLM call cost. This is far more than a tautology and gives an agent a precise model of 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?

The description explicitly states when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete high-stakes examples. It also gives the alternative choice: 'prefer ask_pipeworx for casual lookups.' This is direct, actionable guidance for tool selection.

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

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

Annotations already 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?

With readOnlyHint/openWorldHint/idempotentHint/destructiveHint annotations already covering safety, the description adds substantial behavioral context: parallel decomposition into 5,798 tools, findings packet structure, gaps[] behavior, contradictions[], citation fetchability guarantees, semantic excerpting behavior, and latency expectations (15-60s, up to ~90s for thorough). 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?

Dense and information-rich, but awkwardly constructed. The opening parenthetical is extremely long, and a mid-description clause about ask_pipeworx is garbled and hard to parse. The verbosity is justified by the tool's complexity, but the structure needs cleanup to make the key routing guidance 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 complex tool with 2 params and no output schema, the description covers output format, timing, gaps, contradictions, citation semantics, and tier behavior. Nothing essential is missing for an agent to invoke it correctly. The sibling tool ask_pipeworx is explicitly contrasted.

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 both question and depth. The description materially enriches the depth parameter by explaining what each depth tier actually does: quick=single hop, standard=gap-recovery + contradictions, thorough=iterative + contradictions, and paid status. Also clarifies that question accepts broad/multi-part natural language. This goes well beyond the schema.

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

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

States a specific verb and resource: 'multi-source research across Pipeworx's 1517 STRUCTURED data sources in ONE call' — and explicitly distinguishes itself from open-web search. Names sibling alternatives (ask_pipeworx) and clarifies that it decomposes questions and runs parallel tools, making its unique value proposition unmistakable.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and gives concrete examples. Clearly says to use ask_pipeworx instead when not signed in, and clearly signals that single lookups should go elsewhere. Exclusions and alternatives are explicit.

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

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

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 only declare readOnly/openWorld/idempotent; the description adds substantial behavioral context: fan-out across multiple data sources, USPTO soft-fail after API sunset, GDELT→GNews fallback, empty sections meaning real 'no data', sources_used/sources_failed, and resolved_from/resolved_to behavior. This far exceeds what annotations alone convey.

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

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

The description is front-loaded with usage examples and core purpose, and every section of detail serves a real need. It is dense and long, but the density comes from genuinely important behavioral specifics rather than 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?

For a complex tool with no output schema, the description covers expected return sections, source failure semantics, empty-result meaning, fallback behavior, and edge cases for private companies and name resolution. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful operational nuance by clarifying that 'company' and 'ticker' are interchangeable, that value can be a ticker, CIK, or name, and that names resolve via SEC EDGAR match. It doesn't restate schema but enriches it.

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

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

The description opens with concrete exemplar queries and defines a specific verb+resource: creating a full cross-source profile of a US public company in one parallel call. It explicitly contrasts itself with chaining single-pack SEC/XBRL/news lookups, giving the tool a clear identity.

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 includes an explicit 'ALWAYS PREFER over chaining single-pack lookups' instruction and the trigger condition ('when the user asks for a holistic view'). It also covers the edge case of private companies returning resolved:false, which tells the agent what to expect rather than leaving it to guess.

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 the annotations by disclosing that pairing is unverified, that Kalshi fees are not modeled and spreads are gross, that `temporal_alignment_unknown` is not the same as confirmed alignment, and that unclassified legs are never paired. These behavioral caveats are exactly the kind of context an agent needs before trusting a response. No contradiction with readOnlyHint/idempotentHint/destructiveHint appears.

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

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

The description is exceptionally long and dense, with many safety caveats and field explanations packed into a single text block. It is structured with labels like TWO MODES, RESPONSE, and SAFETY FIELDS, which helps, but the length pushes beyond concise. Most sentences earn their place given the tool's complexity and lack of an output schema, yet it would benefit from tighter organization.

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

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

For a complex tool with three optional parameters and no output schema, the description is remarkably complete. It covers response shape, safety fields, machine-readable codes, per-spread flags, null semantics for temporal alignment, fee caveats, and skipped-comparison counters. An agent has enough context to call the tool correctly and interpret warnings properly.

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

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

Schema description coverage is 100%, so the schema already documents `topic`, `kalshi_event_ticker`, and `polymarket_event_slug` with their override behavior. The description adds the two-mode framing and confirms both modes run the same matcher, which is helpful but largely restates what the schema implies. There is no new parameter syntax or format detail beyond the schema.

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

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

The description clearly states the resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is more specific than the name alone, and the phrase 'same resolving question' helps separate it from generic market comparison tools. However, it does not explicitly contrast itself with sibling tools like polymarket_arbitrage, so differentiation is implied rather than stated.

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 using the two modes: `topic` for pre-mapped shortcuts and explicit ticker/slug for custom pairings. It also warns that pre-mapped topics frequently return compatibility warnings and are not automatically tradeable. It does not name alternatives such as polymarket_arbitrage or polymarket_edges, so there is no 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 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?

Annotations already mark this as read-only, idempotent, and non-destructive, lowering the bar, but the description still adds substantial behavioral detail: multi-source cascading through SEC EDGAR, GLEIF, and OpenFIGI; graceful degradation when enrichment sources are unavailable; explicit `unresolved` fields; and no assertion when multiple FIGI candidates match. None of this contradicts the annotations.

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

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

The description is long but every clause earns its place: the opening examples make the tool immediately recognizable, and the enrichment/edge-case details are behaviorally substantive rather than filler. It is front-loaded with the core rule and supported types before going deeper.

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 two-parameter tool with no output schema, the description covers what gets resolved, supported entity types, input forms, ambiguity behavior, unresolved-identifier behavior, and failure degradation. An agent has enough context to invoke it correctly without needing additional structured information.

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

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

Although schema coverage is 100%, the description adds meaning far beyond the schema: it explains ISIN-to-LEI resolution, entity-name-only passing, why trailing security-class words break FIGI matching, and which input forms map to which supported types. This gives an agent the disambiguation knowledge needed to construct valid 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 uses a specific verb ('resolve') with a clear resource ('user-spoken NAME to canonical/official identifiers') and gives many concrete example phrasings ('ticker for', 'CIK for', 'LEI for'). It also distinguishes itself from siblings by stating that it produces the IDs other tools require as input and should be used first.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID', which is a clear, actionable trigger condition. It does not name sibling alternatives or give explicit when-not-to-use guidance, but the context is strong enough to route an agent 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.