Harrypotter

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes beyond this by explaining the default model, the cost/API-key pass-through mechanism, and the exact return structure per model plus combined view. No contradictions with annotations, and the added context is valuable.

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 a clear purpose. The first sentence states what it does and the output; the second adds model defaults, cost context, return shape, and use cases. No repetition of schema field names, no fluff.

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

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

Given there is no output schema, the description sufficiently explains the return values (per-model {score, confidence, signals, raw_response} + combined view), the model selection, and the API key caveat. It lacks only niche details like rate limits or error behavior, which are not critical for a read-only probe 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 all four parameters, so the baseline is 3. The description adds meaning beyond the schema by clarifying the default model, the conditional need for _apiKey when 'anthropic' is in models, and the 'you pay directly' cost implication. This extra value warrants a 4.

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

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

The description opens with a specific verb ('Probe') and states the resource (LLMs), the target (business/brand/product/topic), and the output (0-100 visibility score). It is clear and distinct from siblings like scan_competitor_ai_presence, though it does not explicitly name any sibling or differentiate itself, so it misses the highest score.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default vs BYO key tradeoff. However, it does not state when not to use the tool or name alternatives, so it lacks explicit exclusion guidance.

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

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

With readOnlyHint, openWorldHint, idempotentHint, destructiveHint all provided in annotations, the description adds context about routing, citation URIs, and tier availability. However, it does not disclose potential failures (e.g., unsupported questions, rate limits) or latency. Still, it's transparent about returning structured answers and the scope of coverage.

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?

Content is front-loaded with the key purpose and preference instruction ('PREFER... START HERE'), followed by scope, examples, and alternatives. Every sentence adds value; no filler or redundancy.

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

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

The tool is complex (routing to 5,564 sources, citation URIs, nuanced question types). The description covers: what it does, when to use it, examples, alternatives, and the availability of a structured answer. Despite no output schema, the return behavior is implied. This level of context is sufficient for accurate selection and invocation.

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

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

Input schema covers all parameters (question plus five aliases) with descriptions, achieving 100% coverage. The description adds examples of valid questions ('Apple's revenue', 'current US unemployment rate') that clarify expected input format, giving it a slight boost above baseline.

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

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

Clear, specific: 'Routes the question to the right one of 5,564 tools... returns the structured answer with stable pipeworx:// citation URIs.' Distinguishes from siblings by naming ask_pipeworx_grounded and deep_research, and explicitly says it's the default 'START HERE'.

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 ('for questions about current or real-world entities, default entry point'), what it does (routes to tools, returns citations), and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistance, deep_research for fan-out). Includes examples of trigger phrases like 'what is', 'look up', etc.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds substantial behavioral context: candidate routing improvements are enabled live when under test, no candidate is currently active, and it 'falls back to nothing' as a full working router. This transparently discloses the experimental nature and current operation state.

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

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

The description is efficiently structured: definition, current status, usage directive, and a clarifying note on fallback. Each sentence adds unique value (the 5,564 tools detail, the 2026-07-26 retirement date, the 'full working router' clarification) without redundancy or 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 router with no output schema, the description specifies the response shape as 'same response shape' as ask_pipeworx, covers experimental behavior, current state, usage, and fallback semantics. Combined with strong annotations, this provides a complete decision-ready overview.

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

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

Schema description coverage is 100% with all six parameters fully documented, including aliases for 'question'. The description only repeats 'same arguments' without adding new parameter-level semantics, so the baseline 3 is appropriate.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx: identical universal router' with the same 5,564 tools, arguments, and response shape. It distinguishes from siblings (ask_pipeworx, ask_pipeworx_grounded) by naming ask_pipeworx and explaining the experimental edge.

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 directs 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. Also clarifies that no candidate is active now, so it matches ask_pipeworx exactly, providing clear when-to-use guidance.

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

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

The description discloses key behaviors beyond annotations: the tool refuses to answer when data isn't in the source (with specific refusal reasons), extracts verbatim quotes, and costs an extra LLM call. Annotations already indicate read-only, idempotent, non-destructive, but the description adds crucial details about refusal handling and evidence extraction, which are not available elsewhere.

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

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

The description is a single, dense paragraph but well-structured with clear cause-effect and cost tradeoff. It front-loads the key benefit and then details behavior, refusal reasons, and performance cost. Slightly long but every sentence adds value.

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

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

Given the lack of an output schema, the description fully discloses the return structure, failure modes, and refusal reasons. It also explains when to use this over ask_pipeworx and the additional cost. Covers prerequisites, behavior, and error handling comprehensively.

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

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

The schema covers 100% of parameters and describes the main 'question' field and aliases. The description reinforces that the input is natural language and that the tool will interpret it. While it doesn't add format details, it contextualizes how the question is used (to route to other tools). This is sufficient given the schema's clarity.

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's a 'hallucination-resistant answer mode for high-stakes reads' that routes to the appropriate tool and extracts answers only from the tool result. It explicitly distinguishes itself from ask_pipeworx by adding a grounded extraction step小学同 is same routing but with guaranteed evidence.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also gives when not to use it: 'prefer ask_pipeworx for casual lookups' and mentions the cost tradeoff (extra LLM call). This clearly differentiates from sibling ask_pipeworx.

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 readOnlyHint and idempotentHint annotations, the description discloses extensive behavioral details: resolver contract with confidence levels and alternatives, safety short-circuiting for low-confidence matches, closed-market status with skip fan-out, wide-spread illiquidity flags, cancellation-rule parsing with EV impact, and news fallback behavior. This gives agents critical context for interpreting results and avoiding mis-sizing bets.

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

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

The description is long, but it is extremely well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, etc.). Every sentence carries operational significance, and the length is justified by the complexity of the tool and the number of edge cases an agent must understand. It is front-loaded with the core purpose and use cases.

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

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

With no output schema, the description must explain return values and behaviors, and it does so thoroughly: result.market fields, result.analysis with model probability and edge warnings, result.evidence keyed by source, resolver contract fields, parent event extractor, news fallback flags, status codes for low-confidence and closed markets, and cancellation-rule risk. This is a complete operational manual for the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some value by showing fan-out examples (e.g., BTC bet → coingecko + fred) and clarifying the depth parameter via 'quick = 2-3 evidence sources, thorough = full fan-out', but the schema already explains all three parameters clearly. The description reinforces but does not fundamentally extend parameter understanding.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on single-bet evidence gathering and market-vs-model comparison, not arbitrage or edge tracking.

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

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

The description gives explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains blocking routes for low-confidence or closed markets, which helps agents decide when not to trust results. However, it does not explicitly name alternative sibling tools to avoid, so it stops short of full when-to-use vs alternatives 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 indicate read-only and idempotent, but the description adds substantial behavioral context: results are sorted by primary metric, off-calendar fiscal years are handled correctly, it runs in parallel, and it returns paired data with citation URIs. This goes well beyond the sparse annotation hints.

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

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

The description is concise yet dense, front-loading usage triggers and purpose before diving into data details. Each clause earns its place: trigger phrases, entity-type behavior, metric notes, and the efficiency gain. Despite its length, it is highly structured and free of 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?

Given the tool's moderate complexity (two types, multiple metrics, grouping, sorting, citations) and the absence of an output schema, the description fully explains what the tool returns: paired data, sorted results, and citation URIs. It also covers edge cases like fiscal-year handling, making it sufficiently 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?

Schema already covers parameter names and types, but the description enriches semantics by specifying exactly what each type pulls: company type retrieves 10-K revenue/net income/cash/debt via SEC EDGAR/XBRL, while drug type retrieves FAERS adverse events, FDA approvals, and trial counts. It also clarifies value formats with examples, adding meaning that the schema alone does not provide.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit trigger phrases and examples. It distinguishes itself from siblings by emphasizing that it replaces 8–15 sequential lookups and is preferred for entity 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?

The description explicitly instructs when to use it ('ALWAYS PREFER over sequential single-pack lookups when comparing entities'), lists trigger phrases, and notes the alternative (sequential lookups). It also defines behavior per entity type, giving clear context for choosing this tool over others.

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 safe read-only behavior, but the description goes further: account/paid-plan requirements, latency expectations (15-60s, ~90s for thorough), gap[] handling with 'never invented', contradictions[] for standard/thorough, resolvable citation_uri policy, and semantic excerpting. No contradiction with annotations.

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

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

The description is long (~300 words) but well-structured: it front-loads account requirements, then covers what the tool does, when to use it, depth behavior, citation/gap semantics, and latency. Each paragraph adds distinct value, though some sentences could be tightened without losing meaning.

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 carries full burden for return-value explanation, and it does so thoroughly: findings packet contents (verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop fields, and latency. It also covers account prerequisites, alternatives, and depth variations, making it complete for a tool of this complexity.

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

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

Schema description coverage is 100% and already explains both parameters in detail (e.g., depth enum states 'standard=3 (default...)' and 'thorough=6 (paid...)'). The description mostly reiterates this information and adds only minor operational context (e.g., thorough needing a paid plan) already present in the schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources... in ONE call'. It explicitly distinguishes from siblings by stating 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups and news topics.

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also includes account prerequisites and fallback instructions if not signed in.

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 hints, so the description does not need to cover those. It adds valuable behavioral context about the return format (top-N tools with names, descriptions, full input schemas, and curated examples, ready to call directly) and prioritization advice ('Call this FIRST'), which goes 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 longer than usual but every sentence carries meaningful information: purpose, usage context, return format, and strategic guidance. The domain list is verbose but useful for task coverage. It is reasonably front-loaded and not redundant.

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 explains return values well (returns top-N tools with names, descriptions, full input schemas, and curated examples). Combined with clear parameter schema and safe annotations, the tool is fully understandable without ambiguity. The complexity is moderate and the description fully covers it.

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

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

Input schema coverage is 100%, with each parameter and alias fully described. The description adds minimal param-specific detail beyond the schema, though it does mention 'top-N' implicitly (limit). Since the schema already does the heavy lifting, a 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 a specific verb ('Find tools') and resource ('by describing the data or task'), and further explains the scope with a broad list of domains. It distinguishes itself from the sibling tools by framing itself as a meta-tool for discovering other tools, which is a unique purpose among the provided siblings.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. It lacks explicit 'when not to use' or named alternatives, but the guidance strongly signals appropriate conditions for use.

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

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

The description adds rich behavioral context beyond annotations: it fans out across multiple data sources, enumerates specific return fields, discloses the USPTO API sunset and soft-fail behavior, and explains the GDELT→GNews fallback. No contradiction with the readOnly/openWorld/idempotent/destructive 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?

A single dense paragraph is efficiently structured: example queries, source fan-out, return components, constraints, and alternative tool reference all appear in ordered, scannable form. Every clause adds value, and key guidance is front-loaded.

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

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

With no output schema, the description fully specifies return contents (cik, filings with URIs, fundamentals, patents, news, LEI) and includes failure/fallback details. It also contextualizes against sibling tools by pointing to resolve_entity for unsupported name inputs, making it complete for agent 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%, so parameters are already well-documented. The description reinforces semantics by providing explicit examples (ticker 'AAPL', zero-padded CIK '0000320193') and reiterating the name constraint, adding practical clarity 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 it provides a full cross-source profile of a US public company, supported by concrete example queries. It distinguishes itself from siblings by explicitly recommending it over chaining single-pack lookups and directing users to resolve_entity for name-based requests.

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

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

Explicit when-to-use guidance is given: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides a when-not-to-use case: 'names not supported (use resolve_entity first if you only have a name).' This clearly identifies alternatives and exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about what is deleted ('previously stored memory') and motivation ('clear sensitive data'), but does not discuss return behavior or edge cases. It does not 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?

Three concise sentences, front-loaded with the core action, followed by usage guidance and sibling pairing. Every sentence contributes value with 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 one-parameter, no-output-schema tool with good annotations, the description fully covers purpose, usage context, and relationships to remember/recall. No critical gaps for an agent to invoke it correctly.

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

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

Schema description coverage is 100% (key: 'Memory key to delete'), so the schema carries the parameter meaning. The description says 'by key' but adds no format or syntax details beyond the schema, so a baseline 3 is appropriate.

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

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

The description uses a specific verb+resource: 'Delete a previously stored memory by key.' It clearly states the action and target, and distinguishes from siblings like remember and recall by the explicit pairing note.

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

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

Explicitly states when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names related siblings with 'Pair with remember and recall,' providing clear selection 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?

Annotations already declare readOnlyHint and idempotentHint, and the description meaningfully adds process details: it fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format as a single text blob. This discloses behavior well beyond the structured annotations, covering what the tool does and what the output looks like.

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 well-structured sentences plus a concise 'Useful for' list. Every sentence provides distinct value: what it does, how it works, and when to use it. No fluff or redundancy.

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

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

For a tool with only 2 parameters and no output schema, the description fully covers the purpose, process, output format, and common use cases. It leaves no significant gaps for an agent to understand when and how to use it.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description adds little new meaning beyond stating 'any URL' and implicitly the link extraction, 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 explicitly states it 'Generate a production-ready llms.txt file' with a specific verb and resource. It details the process (fetches page, extracts title/description/key links, emits standard markdown) and distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence through the focus on generating the file itself.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives strong contextual guidance, but it does not explicitly mention when not to use or directly compare to alternative tools, so it falls short of a 5.

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

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 context about the filtering behavior but does not disclose additional behavioral traits such as pagination or return format. With annotations providing the core transparency, this scores a 3.

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 contains no redundant information. Every word contributes to understanding the tool's function and optional parameters.

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 list tool with rich annotations and no output schema, the description adequately covers what the tool does and how to filter results. It does not explain the return format, but this is not critical for this low-complexity tool, so a 4 is warranted.

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 provides full descriptions for both parameters (house and search) at 100% coverage. The description mentions the house options and name substring filter, but this adds limited meaning beyond what the schema already provides. 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 uses a specific verb ('List') and clearly identifies the resource ('Harry Potter characters'), including subcategories ('wizards, witches, and other figures'). It effectively distinguishes from sibling tools like list_spells, list_staff, and list_students by focusing on the Harry Potter character domain.

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 clearly indicates when to use the tool (for listing Harry Potter characters) and states optional filters (house, name substring). However, it does not explicitly mention alternatives or when not to use this tool, which would merit 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, idempotentHint=true, and destructiveHint=false, so the description doesn't carry the burden for safety disclosure. It adds the fact that results include effects and that filtering is possible, but no deeper behavioral context like pagination or return format. 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?

Two concise sentences with no redundancy. The purpose is front-loaded, and the optional filter is mentioned efficiently. Every word 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?

This is a simple listing tool with one optional parameter. The description covers what it lists, what it returns (spells with effects), and the filtering capability. Annotations handle safety, and no output schema is needed for this complexity.

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

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

Schema coverage is 100% with a well-described 'search' parameter (case-insensitive substring filter). The tool description reiterates 'spell-name substring,' but does not add meaning beyond the 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?

The description clearly states 'List Harry Potter spells with their effects,' using a specific verb and resource that distinguishes it from sibling list tools like list_characters and list_students. The mention of 'effects' adds useful detail about what the tool returns.

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 when to use the tool (when needing spells) and mentions the optional substring filter. However, it does not explicitly exclude alternatives or name when-not conditions, but the sibling tool names make the differentiation implicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context by specifying it returns 'all' records (implying no filtering) and listing the returned attributes, which goes beyond the annotations. It does not contradict annotations and provides modest extra transparency.

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

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

The description is a single sentence that is specific and information-dense. It covers the core purpose and key output fields without any fluff 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?

For a simple list tool with no parameters and no output schema, the description is complete. It identifies the source (HP API), the subset (staff vs other categories), and the exact fields returned, which is sufficient for an agent to use it correctly.

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

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

The tool has zero parameters and the schema is empty (100% coverage). The description does not need to explain parameters, and the baseline for no-parameter tools is 4. It focuses instead on the output, which 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 action ('Return') and resource ('all Hogwarts staff members'), differentiating from sibling tools like list_students and list_characters. It also enumerates the specific fields returned, leaving no ambiguity about the tool's function.

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

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

The description implies usage for retrieving staff data, but it does not explicitly discuss when to prefer this over sibling list tools (e.g., list_students, list_characters). No exclusions or alternative recommendations are provided, so usage context is only implicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is well-covered. The description adds valuable context by specifying the source (HP API), the maximum result count (60), and the list of returned fields, which goes beyond the annotations to set clear expectations about the output.

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, well-structured sentence with the key information up front ('Return all Hogwarts students'), followed by the source, limit, and returned fields. Every part adds value with no redundancy or 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?

The tool is simple with no parameters, but the description compensates for the lack of an output schema by explicitly listing all returned fields and the result limit. The sibling tool context is not necessary for this straightforward list operation, and the description provides enough information 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 tool has zero parameters, and the schema has no properties, resulting in effective 100% schema coverage. Per the rubric, a baseline of 4 is used for zero-parameter tools. The description doesn't need to add parameter-level detail because there are no parameters to document.

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 'Return' with the resource 'all Hogwarts students from the HP API', clearly distinguishing it from sibling tools like list_characters, list_spells, and list_staff. It also enumerates the fields included, making the tool's purpose unmistakable.

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

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

The description clearly indicates this tool is for retrieving Hogwarts students, providing a clear context for when to use it. However, it does not explicitly mention alternatives or exclusions, such as using list_characters for broader character data, so it stops short of the highest guidance level.

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 safety is covered. The description adds value by listing exact return fields and noting that it lists 'active' subscriptions by default, which is useful behavioral context.

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

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

Two sentences: first states purpose and return format, second gives usage guidance. Every word earns its place; no fluff 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?

For a simple list tool with one optional parameter and no output schema, the description is complete: it lists return fields, explains the active-by-default behavior, and contextualizes use relative to subscribe/unsubscribe. Annotations cover safety, so no 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% (single parameter include_inactive with a clear description). The tool description does not need to repeat parameter semantics. The description implies filtering by 'active subscriptions' but does not elaborate beyond schema, aligning with 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 clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes itself from sibling tools like subscribe and unsubscribe by specifying the return fields (id, type, params, etc.).

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 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear when-to-use guidance and implying alternatives (subscribe/unsubscribe).

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

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

Annotations are all false and provide no signals, so the description carries the full burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and quota implications ('Free; doesn't count against your tool-call quota'). 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 longer than average but every sentence serves a purpose: purpose, scoping, exclusions, token mechanics, rate limits, and cost. It is front-loaded with the primary purpose. A slight trim could improve scannability, but the density is justified given the tool's complexity.

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

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

Given 4 params, a nested object, and no output schema, the description covers all critical operational aspects: when to use, what to include, how to track resolution, rate limits, and scope boundaries. It sufficiently addresses how to frame feedback ('in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond the schema. It explains the claim_token round-trip flow, the type categories (bug, feature, data_gap, praise), and clarifies the context object's purpose ('which tool, pack, or vertical this relates to'). The description clarifies that claim_token is used standalone with no other arguments.

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

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

The description states a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It is unambiguous and distinguishes from sibling tools (none of which are feedback-related). The title and first sentence align perfectly.

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

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

Explicit when-to-use is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' 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 mark this as read-only/open-world/idempotent, and the description adds substantial behavioral context: it's self-aggregating, derived from CF analytics-engine, contains no PII (only pack/tool/count), and has variable caching (5min-1h depending on window). This goes beyond annotation coverage and helps the agent understand data freshness and privacy implications.

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

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

The description is well-structured with a clear headline, followed by output specifics and a numbered list of use cases, plus a brief data/caching note. Each sentence provides unique value. It is slightly longer than strictly necessary but remains scannable and front-loaded.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers what's returned (top tools, top packs, total call volume), how it's derived (no PII), and freshness (caching). No critical gaps remain for the agent to safely invoke and interpret this tool.

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

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

The single parameter 'window' is fully documented in the schema with enum values and default. The description adds meaningful semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This extra insight helps the agent choose the appropriate window beyond just reading the enum.

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: showing trending tool usage among AI agents, with specific outputs (top tools, top packs, call volume) and time windows. It distinguishes itself from siblings like discover_tools by focusing on trending/aggregate behavior rather than discovery or individual queries.

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

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

The description explicitly lists three concrete use cases ('Useful for: (1) discovering what data sources are hot for current events, (2) confirming a popular tool is the canonical choice, (3) seeing whether your use case aligns...'), giving clear when-to-use context. It doesn't explicitly state when not to use or name alternatives, but the use cases are highly actionable.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond these: partition_sum deviation threshold (>3pp), placeholder fraction filter (>20%), semantic similarity threshold (≥0.30 Jaccard), and the fill check that prices against live CLOB depth. It also surfaces edge cases like skipped_low_similarity and thin_legs. 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 appropriately front-loaded with the core purpose and well-structured into modes, filters, response, and fill check. It is lengthy but every sentence adds functional value. Minor redundancy exists in repeating the partition_check explanation (e.g., 'sum of YES prices across mutually-exclusive legs') but overall it 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?

Even though there is no output schema, the description defines the response structure explicitly (opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade). It also covers failure modes (skipped_low_similarity, thin_legs, realizable_edge_pp ≤ 0) and points to related tools, making it complete for a tool of this complexity.

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

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

The input schema already describes both 'event' and 'topic' fields with 100% coverage. The description significantly enriches their meaning by specifying accepted formats (event slugs, Polymarket URLs, seed questions), mode-specific behavior, and the type of analysis performed. For instance, 'event' walks child markets and computes both date-axis ordering and partition_check, while 'topic' searches related events and flattens markets for cross-event comparison.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly identifies the tool's function and distinguishes it from siblings like polymarket_edges and polymarket_fill_risk by naming them directly and explaining its unique scanning modes.

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

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

Explicit usage guidance is provided: 'Call with NO args for a trending_scan,' 'pass event for the strongest per-event partition_check,' or 'topic for a themed cross-event scan.' It further recommends event mode 'for a specific market' and topic mode 'for cross-event scanning,' and instructs when not to trade: 'realizable_edge_pp ≤ 0 ... do not trade it.' It also points to a sibling for custom sizing: 'use polymarket_fill_risk.'

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

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

Annotations already mark it read-only and idempotent. The description adds extensive behavioral detail: model families, edge net of slippage, Kelly caps, 24h move warning, tradeable-edge knobs, diagnostics, and caching. It also explains why Fed bets are excluded from ranking, going far 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 a single dense block of text with many technical details. It is structured with labels and sections, but is very long and could benefit from bullet points for readability. Every sentence carries value, but the overall length hurts conciseness.

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 thoroughly documents the response structure including by_segment, per-opportunity fields, diagnostics, and caching behavior. It explains the 'why' behind filters and segments, making it highly complete for an agent to invoke and interpret results.

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

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

Schema descriptions cover 100% of parameters, so the baseline is 3. The description names some knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) but does not add new parameter semantics beyond what the schema already explains; it only summarizes them.

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

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

The description clearly states it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case. It is specific about the resource and action but does not explicitly distinguish 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 description gives a clear use case ('what should I bet on today') and explains the three response segments and how knobs filter results. However, it does not explicitly state when to use an alternative tool or provide exclusions, only implied 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 read-only annotations, the description discloses important behavioral nuances: snapshot gaps ('gaps mean nobody scanned that day'), history limits ('bounded by the 60-day snapshot TTL'), and data granularity ('decay numbers come from daily closes... not intraday'). This adds substantial context about data freshness and interpretation.

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 minimal but well-structured: purpose, args, RESPONSE, LIMITS. Every section adds value, though the 'fresh wide edge...' analogy and some metaphors ('competition clock') are illustrative rather than strictly necessary. Could be trimmed slightly but remains efficient and front-loaded.

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

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

Given no output schema, the detailed explanation of the response structure (tracked, expired, snapshot_dates), field meanings, and limitations is excellent. It covers what, when, how, and edge cases, making the tool fully understandable without external references.

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 both parameters with descriptions (e.g., days lookback with clamp 2-30, window family). The description repeats these details ('days (lookback, default 14, max 30)' and 'window (snapshot family)') without adding significantly new semantics beyond what the schema provides, 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?

The description states a specific purpose: 'Edge persistence and decay telemetry' built from snapshots, answering 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from the sibling tool 'polymarket_edges' by focusing on time-series analysis (first_seen, trend, decay) rather than just current edges.

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

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

It provides clear usage context by framing the question it answers and contrasting fresh vs old edges ('a fresh wide edge and a 3-week-old wide edge are different trades'). It does not explicitly name alternatives or when not to use, but the reference to 'built from daily polymarket_edges snapshots' and the sibling list imply the distinction.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description adds substantial behavioral context: walking the order-book ladder, mode-specific semantics for size_usd, return field details, clamps (10–1,000,000), and the risk of forced directional exposure in basket mode. No contradiction with annotations.

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

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

The description is dense but well-organized with REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections. It front-loads a one-sentence summary, then packs mode-specific behavior, return fields, and usage warnings without redundancy. 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?

With no output schema, the description carries full burden for return values and does so thoroughly, listing all key outputs for both modes (top_of_book, vwap_fill_price, slippage_pp, capture_ratio, thin_legs, max_clean_notional_usd, forced_directional_risk). It covers required params, defaults, modes, and risk factors, making the tool fully actionable.

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

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

Schema coverage is 100%, but the description enriches every parameter: side gets default auto logic in basket, size_usd gets mode-dependent meaning (max spend vs target proceeds vs settlement notional/Shares-per-leg), and market/event are explained as mutually required modes. This goes well beyond the schema 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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by naming polymarket_arbitrage and polymarket_edges, and states exactly what it computes.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why, citing thin-book overround not capturable and partial basket fills creating unhedged directional positions.

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. The description goes far beyond these by explaining the compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0, and the unrelated-events case), temporal_alignment semantics, and the skipped_cross_type/subtype counters. It even tells users that real cross-venue spreads are rarer than the shortcut list suggests, setting expectations for likely return states. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then explains modes, response fields, safety warnings, and a final caveat about tradeability. Despite its length, there is no fluff or repetition; it is well-structured with clear markers (TWO MODES, RESPONSE, SAFETY FIELDS). The length is justified by the complexity of the tool and the absence of an output schema.

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

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

Given the tool's complexity, the absence of an output schema, and rich annotation hints, this description is exceptionally complete. It explains all key response fields (leg-by-leg prices, matched spread top_spreads_pp, compatibility_warning, temporal_alignment, skipped_cross_type/subtype) and even clarifies edge cases like non-equivalent bet shapes and temporal misalignment. The description fully prepares an agent to interpret the tool's output and limitations.

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

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

Schema coverage is 100% (every parameter is described), but the description adds significant meaning by explaining the two modes: topic shortcuts auto-fetch matching events, and explicit kalshi_event_ticker/polymarket_event_slug override the mapped side. It also provides the full list of topic shortcuts in the schema, reinforcing the parameter's enum-like nature, and clarifies that the ticker/slug pair is for custom pairings. This adds value beyond the schema's one-line 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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' This clearly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison between two named venues. It also specifies the two operating modes (topic shortcuts vs explicit tickers), leaving no ambiguity about what the tool does.

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

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

The description gives full context for when to use the tool: for comparing equivalent bet shapes across Kalshi and Polymarket, and it explicitly warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning. However, it does not explicitly name alternative tools for different scenarios (e.g., if a user wanted intra-venue arbitrage), so it falls just short of a 5. The usage context is otherwise strongly implied.

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 safety profile is covered. The description adds valuable behavioral context: the tool is scoped to a user identifier (anonymous IP, BYO key hash, account ID) and that omitting the key lists all saved keys. This goes beyond the 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, each earning its place: the first states the core function, the second provides the use case, and the third explains scoping and relationships to sibling tools. There is no redundancy or filler, and the most important information is front-loaded.

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

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

For a simple tool with one optional parameter and strong annotations, the description is fully complete. It covers what the tool does, when to use it, how to invoke both modes, and the scoping context. No output schema exists, but the description sufficiently implies the returned information (a value or list of keys).

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

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

The schema already documents the 'key' parameter with 100% coverage. The description enriches this by explaining the parameter's role with concrete examples (user ticker, address, research notes) and clarifies that omitting it triggers list mode. This adds meaning beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' This clearly differentiates the tool from siblings like remember and forget, and it outlines the dual-mode behavior (retrieve by key or list all).

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: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the alternative tools for related operations ('Pair with remember to save, forget to delete'), providing clear usage guidance and exclusions.

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

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

The description discloses the mark_read:true side effect (flagging events read), which contradicts the readOnlyHint=true annotation that implies no state changes. This is an annotation contradiction even though the description 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?

Three sentences with no waste: purpose, return payload, filtering/mark_read usage, and alternative endpoint. Front-loaded and efficient.

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

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

Despite no output schema, the description explains return fields, the persisted feed, and the alternative HTTP endpoint. Combined with thorough schema and annotations, it fully equips an agent to use the tool.

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

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

Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The description adds a type example and summarizes filtering but does not significantly enrich meaning 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 'Pull fired events from your subscription feed' and specifies it returns recent alerts with source, citation_uri, and raw payload. It distinguishes itself from sibling tools like recent_changes by focusing on subscription alerts.

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

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

Explicitly mentions 'Polls work fine' and provides an alternative access method via the HTTP endpoint for scripts/dashboards, giving clear when-to-use and alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond these hints: it details the fan-out to multiple data sources (SEC, GDELT/GNews, USPTO), the fallback logic (rate-limited GDELT→GNews), and the soft-fail for patents after API sunset. This gives the agent a clear picture of the tool's runtime behavior.

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

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

Despite being long, every sentence provides essential information: example queries, data sources, parameter formats, return structure, and an explicit alternative. The information is front-loaded and logically organized, making it efficient for an agent to parse.

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

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

Given that the tool has multiple external dependencies and no output schema, the description covers the key return structure (changes[] grouped by source + total_changes + citation URIs) and important edge cases (rate limits, API sunsets). It is comprehensive enough for an agent to know what to expect and how to invoke it correctly.

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

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

The schema already provides 100% coverage with descriptions for all three parameters, so baseline is 3. The description adds extra value by specifying the accepted formats for 'since' (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and for 'value' (ticker or zero-padded CIK). This is more detail than the schema provides, earning a 4.

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

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

The description clearly states the tool's purpose with a specific verb + resource: 'change feed for a company in the last N days/weeks/months' and includes example natural-language queries. It distinguishes itself from the sibling tool entity_profile by explicitly contrasting the dynamic change feed with a static profile.

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 context ('What's new with X', 'latest on Y', etc.) and explicitly names the alternative tool for static profiles: 'Use entity_profile instead when you want the static profile...'. It also mentions fallback behaviors (GDELT→GNews, USPTO soft-fail) which help set expectations on when results may vary.

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 non-read-only, idempotent, and non-destructive. The description adds valuable context about persistence ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping by identifier, going beyond annotations. It does not mention overwrite behavior, but idempotentHint covers that implicitly.

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 core purpose, then usage guidance, then behavioral details and alternatives. Every sentence provides distinct 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 simple key-value write tool with 2 required parameters, the description covers purpose, usage, persistence, scoping, and sibling relationships. It does not mention the return value, but given the tool's simplicity and the presence of annotations, this is a minor omission.

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 both parameters, so the baseline is 3. The description echoes the schema's key-value concept and provides examples, but adds no new parameter-specific semantics beyond what the schema already contains.

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 later reuse, specifying verb ('save') and resource ('key-value pair'). It distinguishes from siblings by naming recall and forget, and provides concrete examples of what to store (ticker, address, preference).

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 guidance on when to use ('Use when you discover something worth carrying forward') and names alternatives ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when not to use, which prevents a 5.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds meaningful behavioral traits: graceful degradation when external sources are unavailable, internal cascading lookups, and explicit listing of unresolved identifiers. No contradiction with annotations.

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

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

The description is front-loaded with useful query examples, but the second half becomes verbose with detailed explanations about enrichment and fallback. While informative, it could be shortened by moving some technical details (e.g., exact sources) to supporting documentation.

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

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

The tool has no output schema, and the description only vaguely mentions that identifiers are labelled and unresolved ones are stated. An agent would need more concrete information on the response structure to parse results reliably. Annotations help (e.g., openWorldHint) but do not substitute for output format clarity.

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 clear descriptions. The description adds nuanced examples like ISIN resolving to legal entity via GLEIF mapping, and explains the graceful fallback behavior. This enriches understanding beyond the schema's enum and type hints.

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 query patterns ("What's the ticker for…") and explicitly states the tool resolves a name to canonical/official identifiers needed by other tools. It clearly distinguishes itself as the go-to for name-to-ID conversion, contrasting with sibling tools like compare_entities and entity_profile.

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 guidance: 'Use FIRST whenever you have a name but need an ID.' It details supported entity types (company, drug) and input formats, including edge cases like ISIN. However, it does not mention when NOT to use this tool or name alternatives among sibling tools for specific sub-tasks.

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 safe read-only, idempotent behavior. The description adds valuable context beyond annotations: it reveals that the tool internally calls ai_visibility_check, ranks results by score, and returns a structured list (score, confidence, signal density). It also notes the first entity is treated as subject, and that the Anthropic model requires an API key. 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?

Description is compact and front-loaded: the first sentence states the core function, the second explains the mechanism, and the third provides an example use case with expected output. Every sentence earns its place, with no fluff.

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

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

For a tool with moderate complexity, the description covers the key aspects: what it does, how it does it (probes ai_visibility_check), what it returns (ranked list with specific fields), and a concrete use case. The absence of an output schema is partially mitigated by explicitly naming the return fields. No critical information 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%, so parameters are fully documented in the schema. The description adds extra semantic nuance, particularly that the first entity is treated as the 'subject' for narrative, and clarifies the tool's behavior of probing each entity. This goes slightly beyond the schema descriptions, justifying a score above baseline.

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

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

Description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities'), explicitly stating it probes each entity with ai_visibility_check, ranks them, and identifies most/least recognized. This clearly distinguishes it from single-entity tools like ai_visibility_check and generic comparison tools like compare_entities.

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

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

The description clearly states the use case ('competitive AI-marketing audits') and provides a concrete example. It implicitly contrasts with single-entity checks by mentioning 'your brand + N competitors', but does not explicitly name alternatives or state when to avoid using it. This is a minor gap.

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

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

Goes well beyond the annotations by disclosing composite behavior (fans out to multiple services), partial failure degradation, and timing (bundlephobia's first measurement can take 5-30s). It also explains what happens on timeout (sources_failed lists it). No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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 adds distinct value: purpose, use case, return value structure, ecosystem scope, and failure behavior. It is front-loaded with the core purpose 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?

Given there is no output schema, the description fully explains return values (summary block fields, per-advisory detail, links, alternative versions). It also covers ecosystem limitations, partial failure behavior, and timing constraints, making it complete for an agent to correctly invoke and understand results.

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

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

Schema description coverage is 100% (both 'package' and 'version' already have detailed descriptions, including scoped package acceptance and default-to-latest). The description adds no extra parameter-level meaning beyond the schema, meriting baseline 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 a specific purpose: a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia for licenses, advisories, size, and tree-shaking. It distinguishes itself from alternatives by explicitly scoping to NPM ecosystem in v1 and noting that other ecosystems fall under deps.dev:version directly.

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 conditions: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also gives clear exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', guiding the agent to alternative tools for other ecosystems.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the truncation behavior with a 200K character cap and flagging, explains the embedding/window approach (BGE-base-en, 500-char windows), and notes that every passage carries an offset for verification. 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 longer than strictly necessary, but every sentence adds valuable context: purpose, use case, technical implementation, and limits. It is front-loaded with the key purpose and organized logically.

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 values (passages, offsets, similarity scores) and the truncation flag. It also covers selection criteria and integration with a sibling tool, making it complete for the agent's needs.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds some behavioral context (truncation, windowing) but does not significantly extend the meaning of the parameters beyond the schema's own examples and descriptions.

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

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

The description clearly states the tool does semantic search inside a fetched record, with specific examples of inputs and outputs. It distinguishes itself from siblings like ask_pipeworx_grounded by explicitly focusing on a subset of already-retrieved text.

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 'Use when the record is too big to cram into the prompt' and explains how it pairs with ask_pipeworx_grounded, providing clear when-to-use guidance and naming an alternative/complement.

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, the description discloses several important behaviors: requiring a Pipeworx OAuth account, SMS phone verification with a 10/day cap, webhook auto-disable after 10 consecutive failures, and that the signing secret is returned only once. These add significant context about side effects and constraints.

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

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

The description is dense but well-structured, front-loading the core action and return value, then covering prerequisites, supported types, and delivery options. Every sentence provides useful information 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?

Given the tool's complexity (5 types, nested params, multiple delivery channels) and no output schema, the description is remarkably complete. It covers auth requirements, type-specific params, delivery behaviors, limits, and the return value (subscription id).

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 parameters (100% coverage), but the description adds practical examples like items:['5.02'] = officer change and clarifies delivery specifics such as the always-on feed. This supplements the schema without being redundant.

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: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription id. This distinguishes it from siblings like unsubscribe and list_subscriptions, and the supported types provide concrete examples.

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, including the OAuth account requirement and that anonymous/BYO cannot persist subscriptions. It explains delivery channels and how to pull the feed (via recent_alerts), but does not explicitly name alternatives or exclusions for when not to use this tool.

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

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

Annotations already indicate read-only and idempotent behavior, and the description adds valuable behavioral context: how it returns example questions, that they are drawn from the live catalog, and that passing an optional topic narrows the spread. 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 dense but purposeful, leading with example queries and packing important details into a structured sentence. Slightly long for a simple tool, but every clause adds needed context for an onboarding entry point.

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 fully explains what the tool returns (category-bucketed example questions with exact tool and argument shapes), how to use it with or without arguments, and the source (live catalog). Complete for the tool's complexity.

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

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

The schema fully describes the single optional `topic` parameter with examples and enum values. The description reinforces this with concrete examples ('finance', 'pharma', 'betting') and explains the effect of omitting it, adding value beyond the schema.

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

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

The description clearly states the tool is the onboarding entry point for discovering what Pipeworx can do, with specific example questions and a description of the return value (category-bucketed examples with tool/argument shapes). It distinguishes itself from siblings like discover_tools by focusing on 'what can I ask' rather than 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 clear timing guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It implies when to use but does not explicitly name alternative tools or state when not to use it, though the context is strong.

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?

Discloses key behavior beyond annotations: ownership enforcement and soft-delete (row deactivated, not deleted) preserving historical events via recent_alerts. This complements annotations like destructiveHint=false and adds real value.

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 concise sentences, no fluff, front-loaded with the core action. Each sentence adds unique information: action, ownership rule, and side-effect behavior.

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, simple tool with good annotations and schema coverage, the description covers action, constraints, and side effects. No output schema is present, but it's not critical for a cancel operation. Sibling tools and annotations round out the context.

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

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

Schema covers the sole parameter id with description linking to subscribe. The description adds the constraint that only own subscriptions can be canceled, which is not in the schema. Baseline 3 due to high schema coverage, plus 1 for the added ownership constraint.

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

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

The description clearly states the action ('Cancel') and the resource ('subscription by id'). It distinguishes this tool from sibling tools like subscribe (creates) and list_subscriptions (lists) by its cancel semantics.

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 on when to use: to cancel a subscription while preserving history. Enforces ownership constraint ('you can only cancel your own subscriptions') as a usage caveat. Does not explicitly name alternatives, but the context is clear enough.

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

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

Beyond the readOnly/idempotent annotations, the description details the dual-pipeline behavior (SEC EDGAR fast path vs. grounded fallback), the full verdict vocabulary, error semantics for could_not_verify (not evidence) vs. unsupported (no source), and the citation/reasoning outputs. This is rich, actionable behavioral context.

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

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

The description is longer than average but well-structured: it front-loads trigger phrases, then covers usage, routing, outputs, and critical caveats. Each sentence contributes distinct value, though the performance claim 'replaces 4–6 sequential calls' is somewhat extraneous. Overall, it earns a high score for organization and necessity.

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

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

Given the tool's complexity and the absence of an output schema, the description fully compensates by listing all verdict values, explaining the error field, and clarifying edge cases like could_not_verify and unsupported. It provides enough detail for an agent to set expectations 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 already provides complete descriptions for both parameters (claim with examples, tolerance_pct with range and default). The description mentions 'percent-delta math' but does not add substantial new semantic meaning beyond the schema. Baseline 3 is appropriate due to 100% schema coverage.

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

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

The description clearly states the tool verifies natural-language factual claims against authoritative sources, using trigger phrases like 'fact check' and 'verify the claim that...'. It distinguishes itself from siblings by describing a specialized claim-verification pipeline with verdict outputs, not just general Q&A or research.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for financial vs. non-financial claims. It does not explicitly name alternative tools or give 'when-not-to-use' exclusions, but the usage context is clear and well-scoped.

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