Bitstamp

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds material operational detail: default model and cost implications (BYO key, pay Anthropic directly), auth requirements for the optional provider, and the precise per-model return shape. This is exactly the kind of context annotations do not convey.

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

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

The description is efficiently written in four sentences (~65 words), front-loading the core purpose and then layering model selection, cost, output format, and use cases. The tautological 'BYO key — you pay Anthropic directly' slightly repeats the earlier _apiKey mention, but overall every sentence adds meaningful information.

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

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

With no output schema, the description clearly explains return values ('per-model {score, confidence, signals, raw_response} + a combined view'), which is essential. It also covers model options, cost/auth behavior, and primary use cases. Combined with exhaustive parameter schema descriptions and safety annotations, nothing critical is missing for a read-only probing 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%, and each parameter already has a clear description (e.g., _apiKey says 'only needed if anthropic is in models. Passed straight through'). The description adds only a marginal cost note about paying Anthropic and repeats the default model, so it does not move beyond the schema-driven baseline of 3.

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

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

The opening sentence is highly specific: 'Probe one or more LLMs for what they know... score visibility (0-100) per model,' clearly naming the verb, resource, and output. However, it does not explicitly differentiate this from overlapping sibling tools like scan_competitor_ai_presence or compare_entities, so it falls short of the top 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 gives concrete use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection (free Workers AI default vs. Anthropic with API key). It does not provide explicit 'when not to use' guidance or name alternative tools, so it earns a 4 rather than 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 read-only and idempotent behavior. The description adds value by explaining it routes to thousands of tools, returns citation URIs, works on every tier, and is fast. This goes beyond the annotations and helps the agent set expectations.

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

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

Although lengthy, every sentence adds value: priority guidance, scope, examples, and escalation paths. It is front-loaded with the key directive 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?

Given the tool's broad scope and lack of output schema, the description covers what it does, when to use it, what to expect (citations, structured answer), and how to escalate. It is sufficiently complete for a default entry-point 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 input schema has 100% coverage with the 'question' parameter and aliases well described. The description adds example questions but no additional parameter semantics beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states this tool answers factual questions by routing to a large set of verified sources and returning structured answers with citations. It explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

Provides explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and spells out when to step up to grounded or deep_research. It also gives concrete example queries, making it easy to decide when to invoke 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?

The description goes beyond annotations by explaining the beta nature, the live candidate testing, current inactive status, and that it is a full working router with no fallback. It also clarifies results are compared to the stable router, providing rich 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 moderately long but every sentence carries meaning: beta status, identical functionality, candidate testing, current state, usage instruction, and comparison to stable. It is front-loaded with the key concept and avoids 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 complex router with 5,529 tools, the description explains the experimental edge, current status, usage, and that the response shape matches ask_pipeworx. It adequately covers the behavior and relationship without an output schema, making it complete for an agent.

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

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

Schema coverage is 100% and all aliases are documented. The description adds that it uses the 'same arguments' as ask_pipeworx, but the schema already fully defines parameters. No additional meaning is necessary, so 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 it is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself as the experimental variant with candidate routing improvements, making its purpose unambiguous.

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

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

The description explicitly says to 'use it exactly like ask_pipeworx when you want the newest routing' and notes the comparison against the stable router. While it doesn't explicitly state 'when not to use,' the context implies stable alternative exists, but naming the sibling would strengthen this dimension.

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 (readOnlyHint, idempotentHint, destructiveHint=false) already establish safety, but the description discloses substantial behavioral traits beyond them: the refusal mechanism with specific refusal_reason values, the evidence verbatim quote, and the extra LLM call cost. This is rich behavioral context that annotations do not convey. No contradiction.

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

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

The description is longer than typical but every sentence carries weight: purpose, routing mechanism, output shape, refusal reasons, use cases, and cost trade-off. It is front-loaded with the key differentiator. Slightly verbose but not wasteful; earns a 4.

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

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

Despite lacking an output schema, the description explicitly documents the success return shape and all refusal_reason values, covering return-values overhead. It also covers cost, use cases, and how it differs from the sibling. For a tool with moderate complexity, this is complete and agent-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% with all aliases well-documented in the input schema. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 applies. The description's mention of 'fills arguments' is generic routing behavior, not parameter semantics.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads' and clearly states what it does: picks a tool, fetches data, extracts answer only from tool result. It also distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding extraction and explicit refusal behavior, making it clearly differentiated.

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 lists high-stakes domains. Also gives a clear when-not-to-use with cost trade-off: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This is definitive usage direction with 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?

Beyond the readOnly/openWorld/idempotent hints, the description discloses resolver confidence levels, low-confidence short-circuit behavior, closed-market status handling, wide-spread liquidity warnings, and resolution-rule cancellation risks (e.g., refund_50_50). This gives the agent essential behavioral expectations for a complex research tool.

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 logically organized into labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Most sentences carry operational value, though it could be tightened; the length is justified by tool complexity.

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

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

With no output schema, the description thoroughly explains all key response fields, status codes, and edge cases (parent_event, resolver alternatives, news fallback, cancellation rules). It is complete for an agent to understand what it will receive and how to interpret 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that 'market' accepts slug, URL, or question text, and by clarifying the tradeoffs of include_raw (summarized vs. full payloads). This goes beyond the schema's field descriptions.

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

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

The description opens with a specific verb+resource ('Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call'), enumerates classifiers, and gives concrete fan-out examples. It clearly distinguishes this from sibling tools like polymarket_edges by focusing on a single bet's research workflow.

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

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

It explicitly lists user intents ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), making when-to-use clear. However, it does not name any alternative tools or explicitly state when not to use it, 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 read-only, idempotent, and non-destructive, so the description adds significant context: it explains data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and returns paired data with citation URIs. This goes well beyond annotations.

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

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

The description is dense but each sentence provides value: query examples, preference rule, data sources, sorting behavior, and return format. It is not excessively long for a tool with two distinct types, though it could be slightly more streamlined.

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

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

No output schema exists, so the description appropriately mentions return values ('paired data + pipeworx:// citation URIs per entity') and data specifics. It covers the main behaviors but could be slightly more explicit about the exact output shape or edge cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning by detailing what data each 'type' retrieves (e.g., revenue, net income for company; adverse-event counts for drug) and mentions that results are sorted by primary metric, which is not in the schema.

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

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

The description clearly states that the tool performs side-by-side comparisons of 2–5 companies or drugs in a single call, using explicit query examples like 'X vs Y' and 'rank these companies'. It distinguishes itself from sibling tools by specifying the exact purpose and scope.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong when-to-use guidance. It also clarifies what each type (company/drug) pulls, but does not explicitly name alternative tools or state when not to use it beyond the preference statement.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds critical behavioral context: account/plan requirements, expected latency (15-60s), the parallel decomposition mechanism, gap[] reporting, contradiction[] output, semantically-excerpted records, and guaranteed-fetchable citations. This far exceeds the annotation baseline.

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 information-dense, covering prerequisites, purpose, exclusions, depth semantics, output format, and performance. Every sentence adds value, though the wall-of-text structure could benefit from more front-loading of the core purpose (the account note appears first). Still, for the tool's complexity, it is appropriately sized.

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

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

With no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], hop field, citation_uri, and contradictions[]. It also covers edge cases like unfindable topics and large-record handling, making the tool's contract unambiguous.

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 descriptions already cover both parameters, but the tool description adds significant meaning by explaining the depth enum's numeric facet counts (quick=3, standard=5, thorough=8), the gap-recovery and contradiction behavior per depth, and explicitly states 'Broad/multi-part is fine — decomposition is the point' for the question parameter.

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 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with 'NOT open-web search'. It distinguishes from siblings by naming ask_pipeworx for single lookups and current-news topics, giving the agent a precise understanding of scope.

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

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

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data' and when-not-to: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Even includes a sign-in prerequisite and fallback if not signed in, plus depth-specific guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating operation. The description adds valuable behavioral context beyond annotations: it discloses that the tool returns top-N relevant tool metadata including names, descriptions, and full input schemas with curated examples, and that results are 'ready to call directly' with no second schema lookup. This clarifies the return behavior and saves the agent from extra steps, though it doesn't cover rate limits or pagination patterns.

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

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

The description is somewhat longer due to the enumerated data domains, but every sentence contributes distinct value: it defines purpose, lists applicable use cases, describes return payload, and gives a usage directive. The structure front-loads the core function and progressively adds actionable detail. The domain list, while long, is directly relevant to helping the agent decide when to use this tool, so 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?

Given the tool's simplicity, the description is remarkably complete. It covers the main action (find tools), the usage context (when to call first), the return format (top-N metadata with schemas and examples), and a clear invocation hint (natural language query). No output schema exists, but the return behavior is explicitly described, so the agent knows what to expect. The tool's purpose and execution path are fully clear without needing additional 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 description coverage is 100%, with each parameter (query, q, task, search, description, limit) documented in the schema. The description mentions 'natural language description' and 'top-N' which loosely aligns with query and limit, but does not add substantive meaning beyond what the schema already provides. The aliases are already in the schema, so the description adds minimal semantic value.

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

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

The description clearly states the tool's function: 'Find tools by describing the data or task.' It specifies the resource (tool catalog) and the action (discover/lookup), and distinguishes itself from siblings by positioning this as the meta-search tool for browsing available data-centric tools (SEC filings, FDA drugs, etc.). The verb 'Find' and the explicit list of covered domains make the purpose unambiguous.

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

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

The description gives explicit usage context: 'Use when you need to browse, search, look up, or discover what tools exist' and directs the agent to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides a clear when-to-use guideline and implicitly differentiates from siblings that provide domain-specific answers rather than an overview of available tools.

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

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

Annotations already indicate safe read-only, idempotent behavior, but the description adds critical behavioral details: parallel fan-out across sources, patent API sunset and soft-fail, GDELT→GNews fallback, and the exact output sections. No contradiction with annotations.

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

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

The description is a dense paragraph but front-loaded with examples. It is somewhat long, yet every sentence contributes useful information (usage, output breakdown, limitations). It could be split into clearer sections but remains efficient for the tool's complexity.

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

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

With no output schema, the description thoroughly enumerates all return fields (CIK, company name, filings, fundamentals, patents, news, LEI), including specific data sources and caveats. It also covers input constraints and fallback behavior, making it complete for agent invocation.

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

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

Schema coverage is 100%, with both parameters already fully described including examples and the name-unsupported caveat. The description largely repeats schema content and adds minimal new semantic detail, 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 the tool creates 'a full cross-source profile of a US public company in ONE parallel call,' with multiple usage examples. It clearly differentiates from chaining single-pack lookups and references sibling tools like resolve_entity, making the purpose unambiguous.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to 'use resolve_entity first if you only have a name.' This clearly communicates when to use this tool versus 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 already declare read-only and non-destructive, but the description adds critical context: the rate includes retail markup and the two legs can differ by several percent. This explains the behavioral nuance beyond the schema and annotations.

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

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

Two sentences: first defines the tool specifically, second gives usage guidance and alternative. Front-loaded and every sentence earns its place. 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 zero-parameter tool with an output schema, the description covers what it is, when to use it, and how it differs from the alternative. No required information is missing.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. Per the rubric, 0 params baseline is 4. The description adds no parameter-specific information, but none is needed.

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

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

The description clearly identifies Bitstamp's own EUR↔USD conversion rate with retail markup, and explicitly distinguishes it from the ECB reference rate. It states the resource (Bitstamp fiat conversion) and the scope (buy/sell prices with markup).

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

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

Provides explicit usage guidance: 'Use when you need the rate a Bitstamp account actually transacts at' and for alternatives, 'For the market FX rate... use ecb_exchange_rate'. This directly addresses when to choose this tool over the sibling.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds usage context but no new behavioral details (e.g., permanent deletion, behavior on missing key). It does not contradict annotations, but adds minimal transparency value beyond 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?

Three short, front-loaded, and purposeful sentences. The first sentence states the action, the second gives usage context, and the third notes related tools. 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?

For a simple one-parameter tool with strong annotations (destructive, idempotent), the description covers the core purpose and usage scenarios. It is complete enough for an agent to select and invoke the tool correctly, including pairing with related memory tools.

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

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

Schema description coverage is 100%, with the schema already documenting 'Memory key to delete'. The description restates 'by key' but does not add format, constraints, or edge-case semantics for the key parameter.

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

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

The description uses a specific verb ('Delete'), names the resource ('previously stored memory'), and specifies the key mechanism. It clearly distinguishes itself from sibling tools like remember and recall, which store and retrieve memories respectively.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Also mentions pairing with remember and recall, providing a clear coordination pattern.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the fetch process, extraction of title/description/key links, and the markdown output format. 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?

The description is three sentences plus a concise list of use cases. It front-loads the primary purpose, explains the process, and gives output context without any fluff. 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?

This is a simple tool (2 params, no output schema) and the description covers purpose, process, output format, and use cases. The annotations handle safety. It is complete for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100% for both parameters (url and max_links), each with clear descriptions. The tool description does not add extra parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Generate a production-ready llms.txt file for any URL'. It details the process (fetches, extracts, emits) and distinguishes itself from sibling tools like ai_visibility_check by focusing on producing 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?

Provides clear context with 'Useful for:' listing concrete scenarios (client sites, own project, competitor auditing). It does not explicitly name alternatives or exclusions, but gives enough guidance for the intended use cases.

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 this read-only and non-destructive. The description adds return-field details (id, type, params, etc.) and clarifies the default scope (active subscriptions), which is useful context beyond the annotations.

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

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

Two concise sentences: purpose and return fields in the first, usage guidance in the second. No redundancy or fluff.

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

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

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

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

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

The only parameter, include_inactive, is fully described in the schema with default false. The description's mention of 'active subscriptions' reinforces the schema but doesn't add additional meaning.

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 lists the caller's active subscriptions, a specific action and resource. It distinguishes from sibling tools like subscribe/unsubscribe by focusing on listing and returning subscription details.

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 advises using the tool before adding more subscriptions or to find an ID to cancel, which provides clear use cases. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds parameter behavior (step, limit, start/end) but does not disclose other behavioral aspects like handling of exclude_current_candle or data availability. It provides some value beyond annotations.

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

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

The description is a single, well-constructed sentence that front-loads the action and connects key parameters to their meaning. There is zero fluff and every word contributes to understanding the tool's function.

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 a straightforward data-fetch operation with an output schema and strong annotations, reducing the burden on the description. The description covers the core purpose and main parameters, with the only notable omission being exclude_current_candle. Overall, an agent can select and invoke the tool correctly with the provided information.

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

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

Schema description coverage is 0% for 6 parameters, so the description must compensate. It explains step, limit, start, and end in plain terms, and mentions currency_pair implicitly. However, exclude_current_candle is left unexplained, leaving a gap in fully understanding the parameter set.

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 ('Fetch') and clearly identifies the resource ('OHLC candlestick data from Bitstamp') and scope ('for a currency pair'). It distinguishes itself from sibling tools like ticker or order_book by focusing on historical candlestick data.

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 OHLC data but does not explicitly state when to use this tool over alternatives nor provide exclusions. Sibling tools like ticker or order_book are not referenced, so guidance is implied rather than direct.

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 safety profile is clear. The description adds that the data is 'live' and specific to Bitstamp, but doesn't disclose behavior like rate limits, error handling, or what happens with invalid pairs. It provides some context beyond annotations but not rich detail.

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

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

The description is two sentences, but the first sentence includes irrelevant context ('European; oldest active crypto exchange — est. 2011') that does not help an agent use the tool. The second sentence is useful and succinct, but the extra historical note makes it less concise than it could be.

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 an output schema present and rich annotations, the description covers the core purpose and use case. However, it fails to explain the optional 'group' parameter and doesn't mention any limitations or prerequisites. Given the tool's simplicity, this is adequate but not comprehensive.

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

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

The description explains the format of currency_pair with the example 'btcusd', which adds meaning beyond the bare schema. However, it does not mention the 'group' parameter at all, leaving its purpose (likely aggregation) undocumented. Since schema coverage is 0%, the description partially compensates but is incomplete.

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 that the tool returns the order book (bids + asks) for a specified crypto pair on Bitstamp. It explicitly mentions the resource, the output, and the pair format, which distinguishes it from sibling tools like ticker (price) and ohlc (candles).

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

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

The phrase 'Use for live depth-of-book on Bitstamp-listed pairs' gives an explicit use case. It doesn't mention alternatives by name, but the context implies it should be used when real-time bid/ask depth is needed, as opposed to price levels or historical data.

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 meaningful behavioral traits: rate-limited to 5 per identifier per day, returns a claim_token for anonymous reports, and explains the follow-up mechanism to read resolution status. It also notes that feedback is free and doesn't count against quota, and that the team reads digests daily. No annotation contradiction exists.

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

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

The description is rightly dense but every sentence earns its place: purpose, usage triggers, scope exclusions, content guidance, claim-token flow, rate limit, and cost. It is front-loaded with the verb and resource, then flows logically through when, what, and how. No redundant or filler content.

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

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

Despite having no output schema, the description fully equips the agent: return behavior (claim_token), how to retrieve status later, rate limits, scope boundaries, and content expectations. It handles the nested context object implicitly by referring to 'which tool, pack, or vertical' via schema descriptions. For a complex, multi-purpose feedback tool, this is exceptionally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics for claim_token by showing exact usage (pipeworx_feedback({claim_token:'pwfb_…'})) and for message content by instructing to describe issues in terms of Pipeworx tools/packs and avoid pasting end-user prompts. This goes beyond the schema's field-level descriptions, though not every parameter receives extra treatment.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from all sibling tools (none of which are feedback-related) and adds scope boundaries explicitly. This is a model of purpose clarity.

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 explicit when-to-use guidance with concrete trigger categories: bug, feature/data_gap, praise. It also gives a clear alternative action for non-Pipeworx tools ('file it with that server instead') and tells users how to verify tool ownership. This fully addresses when and when-not to 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds valuable behavioral context: it reveals the data source ('CF analytics-engine'), privacy ('no PII'), exact data shape ('(pack, tool, count)'), and caching ('Cached 5min-1h depending on window'). This goes well beyond the structured annotations.

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

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

The description is moderately sized and well-structured: a leading definition, a list of outputs, a bulleted 'Useful for' section, and a final metadata note. It efficiently conveys important information, though there is slight redundancy between 'top tools, top packs, total call volume' and 'just (pack, tool, count)'.

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 the burden of explaining return values. It covers the main data points (top tools, top packs, total call volume), time-window choices, caching behavior, and data shape. This is sufficient for a simple, read-only one-parameter tool, though it could mention the default window explicitly (left to the schema).

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

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

The schema has 100% coverage of the single 'window' parameter, including enum values and a descriptive explanation of short vs long windows. The tool description itself does not add additional parameter semantics beyond what the schema already provides, so baseline score is appropriate.

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

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

The description opens with a clear statement of what the tool does: 'What other AI agents are calling on Pipeworx right now.' It precisely lists what is returned (top tools, top packs, total call volume) and distinguishes itself from sibling tools like discover_tools or recent_alerts by focusing on aggregate cross-agent usage trends.

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 enumerates three concrete use cases under 'Useful for:' (discovering hot data sources, confirming canonical tool choice, and checking alignment with aggregate demand). This provides clear when-to-use guidance, though it does not mention exclusions or explicitly name alternatives to avoid.

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

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

Annotations only declare read-only/open-world/idempotent, so the description adds substantial behavioral context: scanning scope (~200 markets), deviation thresholds (>3pp), semantic similarity >0.30, placeholder filtering (>20% returns null), fill check against live CLOB depth, and the explicit warning not to trade when overround exists only at last-trade. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and a front-loaded purpose. Every section contributes unique operational information with no filler. It could be slightly tightened without losing value, but given the tool's complexity the length is justified.

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

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

With no output schema, the description fully specifies the return structure (opportunities[], partition_check{sum_yes_prices, ...}, fill_check outputs). It covers edge cases like low-similarity pairs, placeholder slugs, thin legs, and describes the decision flow from signal detection to tradability. Complete for a complex multi-mode 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 has 100% parameter coverage with basic descriptions, but the tool description adds much deeper semantics: real-world examples for `event` ('fed-decision-may-2026') and `topic` ('Strait of Hormuz traffic returns to normal'), what each mode does internally (walks child markets, flattens markets, runs comparator), and the response shape per mode. This far exceeds the schema text.

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+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It explicitly differentiates three invocation modes (no args, event, topic), clearly distinguishing it from sibling tools like polymarket_edges and polymarket_fill_risk.

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 per mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also names an alternative tool: 'For custom sizing use polymarket_fill_risk', and warns when NOT to trade ('do not trade it' when realizable_edge_pp ≤ 0).

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

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

Even with annotations declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral detail: caching behavior ('Cached 1h at the KV level'), result segmentation (by_segment), edge case handling (placeholder-slug filters, >20% placeholder fraction skipping), output fields (edge_pp_net, kelly_fraction), and diagnostic information (_diagnostics for empty segments). It also discloses nuances like partition arbs always having kelly_fraction_half=0 at parent level. This goes 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 extremely long and unfomatted, with dense jargon and all-caps pseudo-headers instead of markdown structure. It is front-loaded with the purpose in the first sentence, but the sheer volume of detail about model families, gate relaxation thresholds, and internal filters hurts readability. While almost every sentence carries information, the lack of bullets or section breaks makes it harder for an agent to parse. It's not concise, though it is thorough.

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 (9 parameters, 5 model families, 3 response segments, diagnostics) and no output schema, the description is remarkably complete. It details the response top-level structure (by_segment, fed_candidates, _diagnostics), explains why segments may be empty, and covers all filters and knobs. It even provides historical context ('gates relaxed Run 8 from prior 85%/5%/50:1'). This is more than sufficient for an agent to understand what to expect.

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

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

Schema coverage is 100% with descriptions for all 9 parameters, so baseline is 3. The description adds significant value by explaining parameter interactions: 'min_liquidity / max_spread_pp drop opportunities where edge isn't realizable; min_partition_leg_kelly filters partitions by best per-leg Kelly.' It also clarifies that min_kelly never filters partition arbs due to parent-level kelly_fraction_half=0, a non-obvious nuance not present in the schema. This elevates the semantics 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the action (scan and return opportunities), and the distinguishing angle (Pipeworx data vs market price). It also contrasts with siblings by emphasizing model-driven signals and structural arbitrage, not just raw market data.

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

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

The description provides clear usage context: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This tells agents when to use it. It also explains the tradeable-edge knobs and the Fed bets exclusion with reasoning. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes further by disclosing behavioral nuances: snapshots are written only on cache-miss (gaps mean no scan), history depth is bounded by 60-day TTL, and decay is computed from daily closes, not intraday. These details are not present in annotations and add significant 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?

The description is long but densely packed with relevant information. It front-loads the core purpose and then systematically covers arguments, response fields, and limitations. Every sentence adds value, though a more compact rewriting could improve scannability.

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

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

There is no output schema, so the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]) and explaining edge cases (snapshot gaps, TTL limits, signed edge values). It also notes the median lifespan as a 'competition clock', providing practical interpretational context. The tool has no required parameters and is read-only, so the description is sufficiently complete.

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

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

Schema already covers both parameters with descriptions, so baseline is 3. The description adds context by explaining days as 'lookback' with default 14/max 30 and window as 'snapshot family' with default '1wk'. It also clarifies how parameters affect the response (e.g., lookback over snapshot dates). Slight note: description says max 30 while schema says clamp 2-30, but this doesn't materially reduce value.

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

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

Purpose is explicitly stated: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and the key question it answers: 'how long has this edge existed and is it shrinking?' This clearly distinguishes it from sibling tools like polymarket_edges by focusing on history/trend rather than current edge detection.

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 context for when to use: 'a fresh wide edge and a 3-week-old wide edge are different trades (the latter is wide for a reason nobody is willing to take)', implying it should be used to assess edge persistence before trading. It does not explicitly name alternatives or when-not-to-use, but the use case 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?

The description thoroughly discloses behavior beyond the readOnlyHint and idempotentHint annotations. It details the returned fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), explains the interpretation of size_usd in each mode, and calls out edge cases like thin_legs and forced_directional_risk. It also warns about the risk of partial basket fills, which is critical behavioral context for a risk-check tool. No contradiction with annotations exists.

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

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

Despite its length, the description is tightly packed with value and extremely well-structured. It front-loads the core purpose, uses ALL-CAPS markers to delineate REQUIRES, SINGLE-MARKET, BASKET, and USE THIS sections, and every sentence adds unique information (modes, defaults, return fields, risk warning). No filler or redundancy exists, and the length is proportionate to the tool's complexity.

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

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

With no output schema, the description compensates by enumerating all major return values (top_of_book, vwap_fill_price, verdict, theoretical_sum, capture_ratio, thin_legs, etc.) and explaining their meaning. It also covers both modes, parameter defaults, and the key risk scenario (partial basket fills). The complexity of a two-mode risk-check tool is fully addressed, leaving no critical gaps.

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

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

The input schema already provides rich descriptions for all parameters (100% coverage), establishing a baseline of 3. The tool description adds extra semantic value by clarifying the mutual exclusivity of market vs event ('REQUIRES one of market or event'), explaining how size_usd affects ladder walking for single-market mode, and defining the auto side behavior in basket mode. This goes slightly beyond what the schema states, so a 4 is warranted rather than a 5 (which would require even more novel parameter context).

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

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

The description opens with a clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It immediately distinguishes this tool from siblings by naming polymarket_arbitrage and polymarket_edges, and explains that it checks fill feasibility rather than detecting edges. The two modes (single-market and basket) are explicitly defined with distinct purposes.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when NOT to rely on theoretical overround, warning that partial basket fills convert an arb into an unhedged directional position. This clearly differentiates it from sibling tools and gives a concrete decision threshold.

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 sparse annotations (readOnly, idempotent, openWorld), the description discloses numerous behavioral traits: the compatibility_warning conditions (non-equivalent bet shapes vs unrelated events), temporal_alignment's effect on spread validity, and the skipped_cross_type/subtype counters. It also explains why the tool might return 'no arb exists' and cautions about the reliability of pre-mapped topics. This is exceptional transparency about failure modes and data 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 long (~400 words) but highly structured, front-loaded with the core purpose. It uses paragraphs and capitalization for mode names and safety fields, making it scannable. Every sentence adds functional value — explaining modes, response format, safety flags, and caveats. It could be tightened slightly, but the complexity of the tool justifies the length.

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

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

With no output schema, the description must fully explain return values, and it does: it specifies leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. It also covers interpretation and limitations. Given the tool's complexity (3 optional params, no required), this description is self-contained and leaves no significant gaps.

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

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

The schema already documents all three parameters with enums and examples, so coverage is 100%. The description adds meaning by explaining the relationship between topic and the explicit overrides: 'Overrides the topic-mapped Kalshi side' clarifies how the modes interact. It also explains that topic auto-fetches the matching event on both venues, which goes beyond the schema's individual 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly states the tool's function and its unique cross-venue focus. This distinguishes it from siblings like polymarket_arbitrage and polymarket_edges, which are presumably single-platform. The verb 'spread' implies a comparison/calculation, and the resource is explicitly identified.

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 detailed usage context: it explains two modes (topic shortcuts vs explicit event ticker/slug) and gives examples. It also warns that 'pre-mapped ≠ tradeable' and that most topics return compatibility_warning, which sets expectations for when the tool is appropriate. While it doesn't explicitly name alternative tools, it gives clear context on how to interpret outputs and when to expect meaningful spreads.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful context about scoping to an identifier (anonymous IP, BYO key hash, account ID) and the optional key behavior for listing all keys, 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 three sentences, each structured to convey a distinct point: action, usage context, and scoping. No filler or repetition; all sentences earn their place.

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

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

For a simple retrieval tool with one optional parameter and rich annotations, the description fully covers purpose, usage, scoping, and relationships to sibling tools. No output schema exists, but the return value (previously saved value) is self-evident.

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

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

Schema coverage is 100% for the key parameter, which is already described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this with 'omit the key argument' but does not add new parameter-level 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 opens with a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from its siblings by naming remember and forget, making the purpose unambiguous.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also references complementary tools (remember, forget), guiding the agent toward the right alternative for saving or deleting.

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, but the description instructs that setting mark_read:true 'flag[s] returned events read so the next call only shows newer ones,' which is a state-mutating side effect. This directly contradicts the readOnlyHint annotation. Per rubric, this is an annotation contradiction, and the description fails to disclose the state change.

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?

Four sentences, each with a distinct purpose: purpose, return payload, filtering/read flag, and polling/alternative access. No fluff, front-loaded with the verb. Ideal size and structure.

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

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

For a tool with no output schema, the description explicitly describes the return payload (source, citation_uri, raw event payload). It explains mark_read side effects and provides an alternative access method. It omits nothing essential for basic invocation, though it doesn't discuss unread_only or limit defaults (covered by schema).

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

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

Schema covers all parameters with descriptions (100% coverage), so baseline is 3. The description adds valuable meaning for mark_read (explaining the consequence for subsequent calls) and clarifies since and type usage. It doesn't repeat the schema's numeric ranges but adds semantic context for behavior.

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

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

The description opens with 'Pull fired events from your subscription feed,' a specific verb+resource statement that clearly states the tool's function. It distinguishes this tool from siblings like list_subscriptions (managing subscriptions) and recent_changes (change feed) by focusing on alerts from the persisted feed. The phrase 'Returns the most recent alerts the evaluator has written to your persisted feed' further clarifies the scope.

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

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

It mentions that 'Polls work fine' and suggests an alternative HTTP endpoint for scripts/dashboards, giving implementation guidance. It also explains when to set mark_read:true to change subsequent call behavior. However, it doesn't explicitly contrast with sibling tools like recent_changes, leaving some ambiguity for an agent deciding between them.

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/openWorld/idempotent annotations, the description discloses multi-source fan-out (SEC EDGAR, GDELT→GNews fallback, USPTO), the PatentsView API sunset causing soft-fail, and the exact return payload (changes[], total_changes, citation URIs). This gives the agent behavioral expectations well 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 dense but not bloated; every sentence carries information such as fallback logic, `since` formats, and return structure. It's well-structured with one main paragraph and ends with an explicit alternative.

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 (multi-source parallel call, fallback logic, no output schema), the description fully explains inputs, behavior, and return shape in one paragraph. It also notes a future limitation (PatentsView sunset).

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

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

Schema coverage is 100% with each parameter already documented in detail. The description adds minimal extra value, only recommending 'Use "30d" for typical monitoring' and reiterating the supported formats already in the schema.

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

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

The description opens with concrete query examples and explicitly states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also distinguishes from sibling tool entity_profile, making the purpose unambiguous.

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

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

It provides clear usage context with natural-language examples, and explicitly directs users to 'Use entity_profile instead when you want the static profile' – naming the alternative. The description also implies when this tool is appropriate (recent activity/window) versus static profiles.

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

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

Annotations already indicate readOnly=false and idempotentHint=true. The description adds valuable behavioral context beyond annotations: persistence semantics (authenticated vs anonymous sessions, 24-hour retention), scoping by identifier, and the key-value storage model. It does not contradict any annotation.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence provides useful context (when to use, storage model, persistence, companion tools) without redundancy or fluff.

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

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

For a simple memory storage tool with two parameters, no output schema, and good annotations, the description covers all essential aspects: purpose, usage triggers, storage format, persistence, scope, and integration with recall/forget. No significant gaps remain.

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

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

Schema coverage is 100%, so both key and value are well-documented in the schema. The description adds illustrative examples (e.g., 'subject_property', 'target_ticker') and clarifies value can be 'any text,' but this is marginal enrichment over the schema, not essential meaning.

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: 'Save data the agent will need to reuse later,' with a specific resource (key-value pair scoped by your identifier). It distinguishes from siblings by explicitly pairing with recall and forget, and lists 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 when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives: 'Pair with recall to retrieve later, forget to delete,' giving clear context versus sibling tools.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: identifiers are labelled with their source, unresolved identifiers are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully if GLEIF or OpenFIGI is unavailable. It also reveals that each call cascades through multiple endpoints, which is not inferable from annotations.

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

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

The description is somewhat long but well-structured: it starts with examples, states the core purpose, then details supported types and behavioral nuances. It is front-loaded with the essential 'resolve a name to an ID' message, and while a few phrases could be tightened, every section contributes useful information without redundancy.

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

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

Given there is no output schema, the description compensates by explaining what the tool returns conceptually (canonical identifiers with source labels, explicit unresolved list) and covers failure modes (graceful degradation). It also specifies all required inputs and the exact use case, making the tool fully understandable for an agent.

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

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

Schema coverage is 100% (both params have descriptions), but the description greatly expands the semantics: for 'type' it explains the company identity spine (SEC EDGAR, GLEIF, OpenFIGI) and drug structure (RxNorm, RxCUI), and for 'value' it provides concrete examples (AAPL, CIK 0000320193, 'ozempic'). This is far beyond the schema's basic enum and string descriptions.

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

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

The description clearly states the tool's purpose: it resolves a user-spoken NAME to canonical identifiers (CIK, ticker, LEI, FIGI, RxCUI) that other tools require. It opens with concrete example queries ('What's the ticker for…' / 'find the CIK for…') and concludes that it replaces 2-3 manual lookups, making it distinct from siblings like entity_profile or ticker.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' This directly tells the agent when to invoke it and implies not to use it when an ID is already available. It also details the two supported types (company, drug), which helps the agent decide whether this tool is appropriate versus 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 provide readOnlyHint and idempotentHint, so the safety profile is known. The description adds valuable behavioral context beyond annotations: it reveals that the tool makes multiple probes (one per entity), ranks results by score, and returns a ranked list with score, confidence, and signal density. No contradictions found.

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, efficient and front-loaded. The first sentence states the action and mechanism; the second provides the use case and return value. Every sentence contributes meaningfully without redundancy.

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

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

Despite having no output schema, the description clearly states what the tool returns ('ranked list with score, confidence, signal density per entity'). It also covers the use case, the role of the first entity, and the underlying probe mechanism. With rich annotations and full schema coverage, the description fully equips an agent 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?

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by clarifying that 'First entry treated as the "subject" for narrative; rest are competitors', which is not in the schema description. This gives the agent important context for how to structure the entities array.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side' and explicitly mentions the underlying mechanism ('Probes each entity... with ai_visibility_check, ranks by score'). It distinguishes from sibling tools by focusing on multi-entity comparison for AI-marketing audits, which is unique among the listed tools.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and explains that it probes each entity with ai_visibility_check, implying it's for multi-entity scenarios. However, it does not explicitly state when not to use it or directly contrast with alternatives like compare_entities, despite being clear enough for an agent to infer the right 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 the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. This goes beyond the annotations to set latency and error expectations.

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

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

The description is dense but well-structured, front-loading the core composite check, then use case, output summary, ecosystem caveat, and failure behavior. Every sentence carries useful information; the length is justified by the tool's complexity.

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

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

With no output schema, the description compensates by explicitly listing the returned summary fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, and recent alternatives. It also covers partial failure behavior and timeouts, providing a complete picture for an agent.

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

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

Schema description coverage is 100% (both package and version have descriptions). The description does not add additional parameter-level details beyond what the schema provides; it mentions package ecosystem and version behavior in passing. Baseline 3 is appropriate since the schema fully documents parameters.

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

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

The description clearly states the tool's purpose: 'Composite "should I add this npm package to my project" check in ONE call' and details the data sources (deps.dev, bundlephobia). This distinguishes it from sibling tools, which are broad research or market tools. The verb 'scan' and resource 'dependency' are specific and unambiguous.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', directing to an alternative tool 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?

The description goes beyond annotations by detailing the embedding model (BGE-base-en), window size (500-char), and 200K char cap with truncation flagging. These are behavioral traits that annotations do not cover, and no contradiction exists.

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

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

Four sentences cover the purpose, use cases, algorithm details, and limits without fluff. The information density is high 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?

The tool is complex (semantic search with offsets), but the description covers the return format (passages with offsets and scores), the use case, and the pairing companion. The absence of an output schema is compensated by describing what comes back.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches the 'text' parameter with usage context (fetched record, long tool result) and clarifies what a query looks like with examples, 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 opens with 'Semantic search INSIDE a fetched record,' specifying exactly the verb and resource. It contrasts with sibling ask_pipeworx_grounded by clarifying that this tool filters inside an already-fetched text, distinguishing it clearly.

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: when the record is too big to fit in the prompt, and it names the alternative (ask_pipeworx_grounded) for pairing. This gives clear decision 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 goes well beyond the annotations by disclosing the returned subscription id, the always-on feed behavior, delivery channel constraints (phone verification, 10/day SMS cap), and webhook signing details including the one-time secret and auto-disable after 10 failures. This offers rich behavioral context that annotations alone do not provide.

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

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

The description is dense and long due to the complexity of five subscription types and multiple delivery channels, but it is front-loaded with the core action and outcome. Every sentence adds necessary information, though it could be slightly more scannable with bullet lists for the type-specific details.

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

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

Given there is no output schema, the description adequately explains the return value ('Returns the new subscription id'). It covers prerequisites, type-specific parameters, all delivery channels, and failure/constraint behavior, making it self-sufficient for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema, such as 'items:["5.02"] = officer change', '10/day cap', and the need for phone verification. It does repeat several schema details, but the additional context justifies an above-baseline score.

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

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

The description opens with 'Create a proactive monitoring subscription to a live-data event stream,' which is a specific verb+resource statement that clearly distinguishes this tool from sibling tools like list_subscriptions and unsubscribe. It also enumerates subscription types and delivery channels, 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 provides clear usage context: it requires a Pipeworx OAuth account, explicitly states anonymous and BYO cannot persist subscriptions, and gives concrete examples for each subscription type. It does not explicitly contrast with alternatives like recent_alerts or list_subscriptions, so it stops short of full when-to-use vs. when-not guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds useful context by explaining that results are category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog, and that calling with no arguments returns the full spread. This goes beyond basic annotation 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?

The description is a single dense paragraph that front-loads user-facing questions and clearly separates behavioral details. It is efficient in listing categories and examples, though it could be structured with line breaks for improved scannability. Overall, it earns its length.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (category-bucketed example questions with tool+argument shape), how to invoke it (with or without topic), and its role in the broader agent workflow. It fully covers the context needed to use the tool effectively.

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

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

The schema already provides 100% coverage for the optional `topic` parameter with a comprehensive list of options. The description reiterates the parameter ('pass topic') and gives a few examples, but adds little meaning beyond the schema. Baseline 3 is appropriate since the description neither compensates for gaps nor contradicts 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 identifies the tool as an onboarding entry point that suggests example questions, listing concrete intents ('What can I ask Pipeworx?', 'what can you do?'). It distinguishes itself from siblings like ask_pipeworx by framing it as a discovery aid rather than an answering tool.

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

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

Explicitly instructs 'Use this FIRST' when unfamiliar with Pipeworx, and points to learning meta-tools such as ask_pipeworx, entity_profile, and compare_entities. However, it does not explicitly state when NOT to use it (e.g., for direct factual queries), so it lacks a clear exclusion boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by enumerating the returned fields (last price, bid, ask, 24h high/low/volume/vwap, open), which clarifies exactly what 'ticker' means here. 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?

The description is a single, well-structured sentence. It front-loads the core purpose ('Fetch current Bitstamp ticker'), then lists the key fields concisely. Every word earns its place, with 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 read-only tool with one parameter and an output schema, the description is complete. It states the exchange (Bitstamp), the timeframe (current), and the exact fields returned. The output schema covers return structure, and annotations cover safety, so no critical information is missing.

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

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

The schema only defines currency_pair as a string with no description, giving 0% schema coverage. The description compensates by explaining it is a currency pair and providing the example 'btcusd', which clarifies the expected format (base+quote lowercase). While it doesn't list all possible pairs, the example is sufficient for an agent to construct a valid value.

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

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

The description clearly states the tool fetches the current Bitstamp ticker for a currency pair, listing the exact data points returned. It uses a specific verb ('Fetch') and resource ('current Bitstamp ticker'), and the 'current' qualifier distinguishes it from siblings like ticker_hour.

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: this is for fetching the live ticker data, not historical or other market data. It gives an example use case ('btcusd'), but does not explicitly mention alternatives or when not to use it. Still, the context is unambiguous enough for an agent to select this tool for current price information.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds context about the exchange (Bitstamp), the time window, and the specific fields returned (last, bid, ask, high, low, volume, vwap). It does not disclose potential error conditions, rate limits, or formatting constraints, but adds useful scope beyond annotations.

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

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

The description is a single, well-structured sentence that front-loads the action and includes all essential details (exchange, scope, fields, time window). Every word earns its place 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?

Given the tool is simple (one parameter, no nested objects) and has an output schema, the description adequately covers what the tool does and what fields are returned. The main gap is not explicitly clarifying how it differs from the sibling 'ticker' tool, but this is not essential for basic usage.

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

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

The schema provides 0% description coverage for the only parameter 'currency_pair'. The description compensates with an example ('btcusd') and implies the format, but does not provide explicit rules on case, valid pairs, or formatting patterns. This is partial compensation but leaves ambiguity.

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 ('Fetch') and resource ('Bitstamp last-hour ticker stats'), clearly specifying the currency pair and time window ('past 60 minutes'). This distinguishes it from the sibling tool 'ticker', which likely refers to the current ticker.

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 60-minute historical ticker stats, but does not explicitly contrast with sibling tools like 'ticker' or 'ohlc'. There is no direct 'when to use this instead' guidance, so the usage context is inferred rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds context about the specific exchange (Bitstamp) and the metadata fields included, but does not disclose further behavioral details such as pagination or data freshness, which is acceptable given the annotation 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?

The description is a single sentence that front-loads the action and resource, then enumerates the metadata fields. Every word adds value with no redundancy.

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

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

Given the tool has no parameters, an output schema is present, and annotations cover safety, the description provides all necessary context. It specifies the scope ('all'), the exchange, and the metadata fields, making it complete for its 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 tool accepts no parameters, and the schema coverage is 100% with an empty object. The baseline for 0-parameter tools is 4, and the description appropriately focuses on the output rather than parameter semantics.

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

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

The description uses a specific verb 'List' and identifies the resource 'all Bitstamp trading pairs' with metadata fields, clearly distinguishing it from sibling tools like ticker or order_book that deal with price/order data.

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 clearly states the tool returns trading pair metadata, implying it should be used when this information is needed. However, it does not explicitly mention alternatives or exclusion criteria, so it stops short of full usage guidance.

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

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

Annotations already declare this as read-only and idempotent, so the safety profile is covered. The description adds valuable context by explaining the time parameter as a lookback window (minute, hour, day) and listing the return fields (trade id, price, amount, type, timestamp), which goes beyond the annotations. It does not mention pagination or result limits, but the output schema exists.

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

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

Two sentences, no redundant phrasing. The first sentence states the core purpose and scope; the second clarifies the optional parameter and return fields. 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?

For a simple two-parameter tool with an output schema and full annotations, the description provides everything needed for selection and invocation: what it does, what the parameters mean, and what to expect in the response. No significant gaps.

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

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

Schema description coverage is 0%, so the description carries the burden; it explains both parameters: 'currency pair' is the trading pair, and 'time' is an optional filter with specific values (minute, hour, day) defining the lookback window. The schema examples reinforce the format (e.g., 'btcusd'), making this sufficient.

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

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

The description starts with 'Fetch recent Bitstamp trades for a currency pair,' a specific verb-resource pair that clearly distinguishes this from siblings like order_book (current orders) or ticker (price). It also scopes the tool to trades for a currency pair, leaving no ambiguity.

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

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

The description implies the tool is for retrieving recent trade history, which is a clear context. It does not explicitly compare with alternatives (e.g., 'for real-time prices use ticker'), but the optional time filter gives a sense of when to use the tool for custom lookbacks. No misleading 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 readOnlyHint false, destructiveHint false, idempotentHint true. The description adds valuable behavioral context beyond these annotations: it explains ownership enforcement and that the row is deactivated (not deleted) so history remains available. This is exactly the kind of disclosure that helps an agent understand side effects and invariants.

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

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

Two sentences, front-loaded with the core purpose, followed by the key behavioral detail. No filler or redundant information.

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

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

Given the simplicity of the tool (1 parameter, no output schema, rich annotations), the description covers all essential aspects: purpose, ownership constraint, and soft-delete behavior while referencing recent_alerts appropriately. It is sufficient for correct 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?

The input schema already provides a clear description of the parameter id ('Subscription id (uuid) returned by subscribe'), and schema coverage is 100%. The description adds no further parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It uses a specific verb (Cancel) and resource (subscription), and implicitly distinguishes itself from siblings like subscribe and list_subscriptions by focusing on cancellation.

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

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

The description provides clear context on when to use the tool (cancelling a subscription) and adds important usage constraints such as ownership enforcement. It also references recent_alerts for historical events, implying a related alternative, but does not explicitly name other sibling tools or state when not to 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?

Beyond the readOnly/idempotent annotations, the description discloses key behavioral semantics: the distinction between could_not_verify (check did not happen) and unsupported (no source covers it), the routing behavior, and the tolerance override. It also explains that could_not_verify must not be shown as evidence, which is critical for safe usage.

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

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

The description is well-structured and front-loaded with the purpose and common phrasings. It is somewhat lengthy, but every sentence (including the IMPORTANT note and the 'Replaces 4–6 calls' value prop) earns its place for a complex tool.

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

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

With no output schema, the description fully explains what is returned: the list of possible verdicts, the actual value with pipeworx:// citation, and reasoning. It also covers edge-case semantics (could_not_verify vs unsupported), routing, and tolerance behavior, 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 provides thorough descriptions for both parameters (100% coverage). The description adds extra value for tolerance_pct by explaining how to set it for hallucination detection and the default cap, and gives concrete examples for claim.

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

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

The description clearly states this is a natural-language claim verification tool with specific verb+resource (verify claims against authoritative sources). It provides example phrasings and explicitly differentiates from general-purpose tools by noting it replaces 4–6 sequential calls for fact-checking, making it the dedicated fact-check tool.

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

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

It explicitly instructs to use 'whenever the agent needs to check whether something a user said is factually correct' and details routing between the SEC EDGAR structured path and the grounded pipeline. It gives good contextual guidance, though it does not explicitly name alternative sibling tools to avoid.

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