Bundesbank De

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds meaningful behavioral context: cost disclosure ('you pay Anthropic directly'), default model behavior, and the exact return structure (per-model score, confidence, signals, raw_response + combined view). No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the primary purpose, then default model/cost, return structure, and use cases. Every sentence carries essential information without fluff, making it appropriately sized and well-structured.

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

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

Given the lack of an output schema, the description adequately explains the return values. It covers default behavior, optional API key, and use cases. Minor omissions: no mention of rate limits, error behaviors, or what 'signals' specifically contain, but overall it is sufficiently complete for a read-only probe tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model for `models`, the pricing implication of `_apiKey`, and the output format that parameters influence. This is supplemental rather than just repeating schema descriptions, justifying a 4.

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

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

The description clearly states the tool's function: probing LLMs to assess what they know about a given entity and scoring visibility from 0-100 per model. The verb 'probe' + specific resource ('LLMs') + output ('score visibility') makes it highly specific and distinguishes it from generic search tools. It also mentions default model and optional Anthropic, further clarifying scope.

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

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

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to pass `_apiKey` for Anthropic. However, it does not explicitly mention when to use this tool over its sibling `scan_competitor_ai_presence`, nor does it state exclusions. This is clear context but lacks explicit alternative differentiation.

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=true, openWorldHint=true, idempotentHint=true, which cover the safety profile well. The description adds valuable context about routing behavior (routes to one of 5,347 tools), citation URIs (pipeworx://), and return format (structured answer). No contradiction with annotations. Could add rate-limit or failure behavior but with this annotation coverage, the description does more than enough.

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 information-rich — every sentence earns its place, and the examples are concrete and useful. Slightly verbose for a default entry-point tool, but the length is justified given the tool's broad domain coverage. Front-loaded with the critical 'PREFER OVER WEB SEARCH' signal.

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

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

For a single-question tool with no output schema and no nested objects, this description is nearly complete. It covers the query types, gives six concrete examples, names escalation paths, and explains the routing mechanism and citation format. No output schema means the description correctly focuses on input expectations and behaviors.

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 documents 'question' with alias support (query, q, prompt, text, input). The description explains the semantic role: accepts natural language questions and 'fills arguments' automatically. It adds the context that the question can be broad ('factual question about real-world entities') beyond what the schema states.

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 is specific and comprehensive: 'PREFER OVER WEB SEARCH for questions about current or historical data' with a clear verb ('routes the question') and resource ('5,347 tools across 1393 verified sources'). It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by naming them and explaining when to use each.

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?

Extremely explicit guidance: 'START HERE for most questions', 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research), and even specifies when not to rely on it ('breaking news' handled differently). Lists trigger phrases like 'what is', 'look up', 'find' to help selection.

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

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

Annotations provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, which cover the safety profile well. The description adds valuable context: that results are compared against the stable router for merge decisions and that routing improvements may be live intermittently. It doesn't contradict annotations.

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

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

The description is reasonably sized but has some noise: 'the last was retired on outcome evidence 2026-07-26' and 'results are compared against the stable router to decide what merges' are details that could be condensed. The core message is clear and front-loaded, but the beta-mechanics exposition is a bit rambling for tool-definition purposes.

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 this is a single-parameter router mirroring ask_pipeworx, and annotations already declare safety properties, the description covers the essence: identical semantics to ask_pipeworx, experimental routing behavior, and no fallback. Some could argue the beta-comparison mechanics are over-specified, but the description is complete for what an agent needs to use it correctly.

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

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

Schema description coverage is 100% and the schema already documents the question parameter plus five aliases with descriptions. The description adds that arguments are 'identical' to ask_pipeworx, which is useful cross-tool context, but doesn't add much a dedicated parameter semantics beyond the schema baseline. Baseline 3 with slight credit for the cross-reference.

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

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

The description clearly states this is a beta/experimental variant of ask_pipeworx with identical routing and candidate routing improvements. It explicitly distinguishes from ask_pipeworx (same functionality, experimental routing). However, the verbose framing about 'candidate routing' and 'retirement dates' adds noise beyond what's needed.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes it falls back to nothing / is a full working router. It differentiates from the stable ask_pipeworx sibling. However, it doesn't explicitly say when NOT to use it vs alternatives (e.g., ask_pipeworx_grounded), and the beta-vs-stable choice criteria are somewhat implicit.

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

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

Despite the annotations declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: the return contract with the exact refusal_reason enum values, the evidence-verbatim-quote guarantee, and the failure modes (refusal when data doesn't directly answer). This goes well beyond what annotations provide and is critical behavioral disclosure.

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 information-rich, covering purpose, routing, extraction behavior, return contract, refusal reasons, use cases, and cost tradeoffs. It's front-loaded with the core distinction ('hallucination-resistant answer mode'). While slightly long, every sentence earns its place except perhaps the exhaustive refusal_reason enum which is arguably schema-worthy detail. Still, it's well-structured and efficient.

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

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

For a complex tool with no output schema, the description is remarkably complete: it documents the return object shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), lists all refusal reasons, explains routing and cost, and gives clear usage guidance. No critical behavioral or usage gap remains for an agent to discover by trial and error.

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

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

Schema description coverage is 100% — all 6 parameters are question aliases documented in the schema. The description adds no parameter-specific semantics beyond what the schema provides (the schema already explains the aliases). Baseline 3 is appropriate since the schema does the heavy lifting and there's nothing further the description needs to add for a single-question tool.

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 (ask/fetches) plus a clear resource (Pipeworx tool routing across 5,347 tools/1393 sources) and adds a distinct differentiator: the grounded/evidence-extraction behavior. It explicitly distinguishes from ask_pipeworx by naming it and explaining the difference (extraction vs casual). This is exemplary 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?

The description gives explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and names concrete high-stakes domains (financial verdicts, legal claims, medical lookups, public statements). It also explicitly states when NOT to use it ('prefer ask_pipeworx for casual lookups') and discloses the cost tradeoff (one extra LLM call).

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

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

Annotations already establish the tool as read-only, open-world, idempotent, and non-destructive. The description adds substantial behavioral context beyond these: safety mechanisms (low-confidence short-circuit, closed-market handling), wide-spread illiquidity warnings, resolution-rule risk (cancellation_rule parsing), and the resolver contract (market_match_confidence, alternatives, suggestions). It also explains when fan-out is skipped and how news fallback works.

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 explicit section labels (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). Every sentence adds substantive information, but the sheer length may exceed what an agent needs for initial comprehension. Front-loading of purpose and usage helps, so it 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?

Without an output schema, the description fully explains return value shapes: result.market fields, result.analysis fields (model_probability, edge_pp, kelly_fraction_half, 24h-move warning), result.evidence keyed by source, resolver contract fields, parent event structure, and news fallback fields. It also covers blocking statuses and safety behaviors, making the description complete for this complex tool.

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

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

Schema description coverage is 100%, with each parameter (market, depth, include_raw) already documented clearly. The description adds no new parameter-level details beyond what the schema provides, though it does provide examples of market slugs/URLs. Baseline 3 is appropriate because the schema carries the 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+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines the tool's purpose and distinguishes it from sibling tools by focusing on a single market research task with fan-out to category-specific data packs. The classifier list and fan-out examples further clarify exactly what the tool handles.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not explicitly name alternatives or say when not to use, but the clear purpose and examples effectively imply when this tool is appropriate versus other Polymarket tools.

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

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

The description adds substantial behavioral context beyond the annotations: it details that company pulls latest 10-K financials (revenue, net income, cash, long-term debt), handles off-calendar fiscal years, sorts results by primary metric, and returns paired data with pipeworx:// citation URIs. These are valuable behavioral traits not present in annotations.

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

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

The description is front-loaded with the core purpose and trigger phrases, then expands with specific behaviors. Every sentence adds value—usage preference, data source, fiscal-year handling, sorting, and return format—without repetition or filler. It is appropriately detailed 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?

Given there is no output schema, the description adequately explains the return format (paired data + citation URIs) and behavioral outcomes (sorted results, metric details). It covers both entity types and references efficiency (replacing 8–15 lookups), making the tool's behavior 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%, but the description enriches both parameters: it explains that 'type' selects the entity kind and 'values' holds 2–5 tickers/CIKs or drug names, with concrete examples. It also describes what metrics each type retrieves, adding meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It provides trigger phrases, the exact action, and explicitly distinguishes itself from sequential single-pack lookups, making its scope 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 explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' naming the alternative and stating when to use this tool. It also explains type-specific usage for company vs. drug, giving clear context for invocation.

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

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

The description adds substantial value beyond the readOnly/idempotent annotations: it states the return is SDMX 2.1 XML, explains that the DSD id may differ from the dataflow id, notes the dimension order in DimensionList, and explains the withCodes default behavior. This gives the agent a clear picture of what to expect.

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

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

The description is efficiently structured: it opens with the core purpose, then gives return format, then the DSD-id caveat, then parameter guidance. Every sentence adds relevant information without padding or repetition.

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

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

With no output schema, the description adequately covers return format (SDMX 2.1 XML, DimensionList), the relationship between dataflow and DSD ids, and parameter behavior. It is sufficiently complete for an agent to select and invoke the tool correctly without 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 coverage is 100% and the schema already documents both parameters. The description adds extra context by explaining that flowRef is a dataflow id that gets resolved to a DSD, and clarifies the withCodes default and its effect on codelist inclusion, which goes beyond the schema baseline.

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

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

The description clearly states the tool gets the data structure definition (DSD) for a dataflow, including dimensions and valid codes, and explicitly ties this to building a series key for get_series. This specific verb+resource distinguishes it from sibling tools like list_dataflows or get_series.

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 a clear use case (needed for get_series) and explains how to invoke the tool with a flowRef. However, it does not explicitly mention alternatives or when not to use it, so it lacks the explicit exclusion guidance that would earn a 5.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context beyond these: gaps[] never invented (honesty guarantee), semantic excerpting behavior for large records, contradictions[] for disagreement flagging, hop field semantics, timing expectations (15-90s), and that it returns empty gaps for non-catalog topics. It also discloses the parallel-routing architecture which massively informs agent 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 long but information-dense; nearly every sentence introduces new facts that an agent needs for correct selection and invocation (sibling differentiation, auth, timing, gaps, contradictions, hop semantics). It front-loads the critical account requirement and the 'not open-web' caveat. Some redundancy exists (contradictions scan mentioned in both depth and standard/thorough descriptions), but overall each sentence earns its place.

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

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

For a 2-param tool with 100% schema coverage and rich annotations, the description goes well beyond the minimum. It explains the return packet structure (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), the gaps[]/contradictions[] output fields, iteration behavior across depth tiers, mention of 5,347 tools and 1,393 sources, and the ~90s worst-case latency. This is exemplary completeness for a tool of this complexity.

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

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

Schema coverage is 100%, both parameters have descriptions. The depth parameter's enum values are documented in the schema, but the description adds valuable semantic context (e.g., thorough adds lead-chasing and returns contradictions vs standard's gap recovery), and question is described as 'broad/multi-part is fine — decomposition is the point' which clarifies acceptable input. The description meaningfully extends schema info on depth 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 clearly states the tool's purpose: grounded multi-source research across Pipeworx's 1,393 structured data sources in one call, decomposing questions into facets routed to 5,347 tools in parallel. It uses specific verbs ('decomposes', 'routes', 'returns') and explicitly differentiates from siblings by stating 'this is NOT open-web search' and naming ask_pipeworx as the alternative for single lookups and breaking news.

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

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

The description gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and clear when-not-to-use exclusions ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'). It also specifies account requirements and which depth tier needs a paid plan, naming concrete alternative 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 readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable behavioral context beyond annotations: it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that results are 'ready to call directly, no second schema lookup needed.' This informs the agent about response format and utility without contradicting annotations.

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

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

The description is moderately long but every sentence earns its place: it states purpose, lists domains, explains return format, and gives usage directive. The front-loaded core purpose is clear. Slightly verbose domain list, but it helps the agent formulate queries, so not excessive.

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 explicitly details the return content: 'names, descriptions, and full input schemas (with curated examples).' It covers what the tool does, when to use it, parameter semantics, and output structure. This is complete for a discovery tool with read-only annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description enriches parameter understanding by listing concrete domains the tool covers (SEC filings, FDA drugs, FRED, etc.) and explaining that query accepts natural language descriptions. It also introduces the 'top-N' concept linked to the limit parameter, adding value beyond the schema aliases.

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

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

The description opens with a specific verb+resource ('Find tools') and clearly defines the scope: 'by describing the data or task.' It distinguishes this tool from its siblings by positioning it as the discovery entry point ('Call this FIRST when you have many tools available'), which is unique among the listed sibling tools.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist' and provides a directive to 'Call this FIRST when you have many tools available.' It also hints at exclusions by saying 'not just one answer,' implying this is not for direct single-answer tasks. This is clear and actionable.

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

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

Beyond the readOnly/idempotent annotations, the description discloses behavioral details: parallel fan-out across SEC, XBRL, USPTO, news, GLEIF; soft-fail for patents due to sunset; GDELT→GNews fallback; and specific output fields. This gives the agent a realistic expectation of behavior without contradicting annotations.

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

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

The description is dense but not wasteful; it front-loads trigger phrases and purpose, then packs in output details, fallbacks, and usage constraints. Slightly long, but every sentence adds value for a complex multi-source 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 must explain return values, and it does so thoroughly: CIK, filings with URIs, fundamentals, patents, news, LEI. It also covers limitations and fallback behavior, making the tool broadly understandable despite 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 input schema already documents both parameters fully (type enum, value as ticker/CIK, name unsupported). The description reiterates this but adds no new semantic details beyond examples. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It uses specific verbs and resources, and distinguishes itself from siblings by explicitly recommending it over single-pack lookups and pointing to resolve_entity for name-only inputs.

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

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

Provides explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes when NOT to use it: 'names not supported (use resolve_entity first if you only have a name).' This clearly orients the agent relative to 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 destructiveHint=true and readOnlyHint=false, so the destructive nature is disclosed. The description adds context about clearing sensitive data and that it acts on previously stored memories, but does not elaborate on edge behaviors (e.g., no-op for nonexistent keys) beyond what annotations imply via idempotentHint=true. 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 short sentences, front-loaded with the primary action, followed by relevant use cases and sibling tool relationships. Every sentence serves a purpose, with no redundant or vague wording.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, use cases, and related tools. It does not explicitly describe return values or post-condition behavior, but given the simplicity and strong annotations, it is sufficiently complete for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% for the single 'key' parameter, with a clear description 'Memory key to delete'. The description only says 'by key', adding no additional semantic detail beyond the schema, so the baseline score of 3 is appropriate per the rubric's high-coverage rule.

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 'Delete a previously stored memory by key,' using a specific verb and resource, and distinctly identifies it as the deletion counterpart to remember/recall among the sibling tools. It goes beyond the name 'forget' by explaining the exact action and scope, 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 provides explicit when-to-use guidance: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, giving relational context, but does not explicitly state when not to use it or list direct alternatives for deletion. Overall, usage context is clear and practical.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful process detail: fetches the page, extracts title/description/key links, and emits standard markdown. 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?

Three sentences, front-loaded with the core action, followed by output details and use cases. No filler or redundant repetition of schema information.

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

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

For a simple two-parameter tool, the description fully covers what the tool does, how it behaves, and what the output will be. It even mentions where to deploy the output (site-root/llms.txt), making it complete even without an output schema.

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

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

Schema description coverage is 100%, with both parameters (url, max_links) already described including defaults and limits. The description adds no new parameter semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description names a specific verb ('generate') and resource ('llms.txt file for any URL'), and clearly states the output format and purpose. It distinguishes itself from siblings by focusing on producing the file rather than scanning or checking AI presence.

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

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

Provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not explicitly mention when not to use it or name alternatives, but the context is clear.

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, so the description only needs to supplement behavioral details. It adds key semantics, wildcarding ('Leave a dimension empty to wildcard it'), output format (SDMX-JSON), and date formats, which go beyond the schema. This is a rich addition.

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

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

The description is four sentences, front-loaded with the main purpose, and each sentence adds a distinct piece of practical guidance (format, key format, discovery tool, filtering). No wasted words.

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

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

For a 6-parameter tool with no output schema, the description covers the core concepts: data source, key construction, wildcards, and filter options. It also references the sibling discovery tool, making it self-contained. The only omission is the 'detail' parameter, but that is fully covered by the schema, so completeness is high.

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 property descriptions, but the description adds contextual examples: flowRef example 'BBEX3', key example 'D.USD.EUR.BB.AC.000' with explanation, and wildcard syntax. This clarifies the abstract schema definitions, raising the value beyond baseline.

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

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

The description opens with a clear verb+resource statement: 'Pull observations for a Bundesbank series as SDMX-JSON.' This distinguishes it from sibling tools like dataflow_structure or list_dataflows, which serve different discovery/list 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?

It explicitly instructs to 'Use dataflow_structure to discover the dimensions/codes for a flow,' pointing to an alternative when users lack dimension codes. It also clarifies when to use filtering parameters (lastNObservations vs date range), giving practical examples.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds value by specifying the return format (SDMX 2.1 structure XML), the agency scope (BBK), and the behavior when flowRef is provided. This goes beyond what annotations convey.

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

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

The description is three sentences, front-loaded with the primary purpose, and each sentence provides distinct value: what the tool lists, the output format and scope, and how to narrow the result. No wasted words 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 read-only listing tool with one optional parameter and no output schema, the description covers the output type, the list scope (all under BBK), the meaning of a dataflow, common identifiers, and the effect of the flowRef parameter. This is sufficiently complete for an agent 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?

Schema coverage is 100% for the single parameter flowRef, with a clear description in the schema. The tool description adds extra nuance: 'includes its DataStructure reference' when a flowRef is passed, which is not stated in the schema. This meaningful addition justifies a score above baseline.

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

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

The description clearly states the tool's purpose: 'List the available Bundesbank statistics dataflows' with specific context that each dataflow is a series collection queryable via get_series. It distinguishes itself by mentioning the operation is listing, and the inclusion of well-known flow IDs adds specificity.

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 connects to get_series as the way to query data inside a dataflow, and explains that passing a flowRef fetches a single dataflow with its DataStructure reference. While it doesn't state explicit exclusions or mention the sibling dataflow_structure tool, the context is clear enough for an agent to decide when to use this tool.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context by specifying the 'caller's' scope and the exact return fields, which is more than just restating annotations. No contradictions or hidden behaviors.

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

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

The description is two sentences with no filler. It front-loads the core purpose and then immediately provides usage context, making every word earn 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 read-only list tool, the description covers what it does, what it returns, and when to use it. Since there's no output schema, listing the return fields in the description is sufficient and 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 for the single parameter (include_inactive) is 100%, so the description does not need to explain it. The description adds no extra parameter semantics but does not need to, as the schema fully covers it.

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

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

The description uses a specific verb+resource structure: 'List the caller's active subscriptions' and enumerates the exact return fields (id, type, params, etc.). It clearly distinguishes from sibling tools like subscribe/unsubscribe by focusing on the list operation.

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 the tool: 'review what you're monitoring before adding more or to find an id to cancel.' This references alternatives (subscribe, unsubscribe) and gives contextual 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?

Annotations are all false, so the description carries the burden. It adds useful context: rate limit (5/identifier/day), free/no quota impact, and that digests affect roadmap. It doesn't describe return behavior, but the submission nature is clear. 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?

Five sentences, each serving a purpose: purpose, use-cases, formatting directive, roadmap impact, and rate-limits. No filler.

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

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

The description covers purpose, use cases, formatting rules, rate limit, and impact, which is sufficient for a feedback tool. It doesn't state what response to expect upon submission, a minor gap given no output schema.

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

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

Schema covers all parameters with descriptions, but the tool description adds param-level guidance: 'Describe the issue in terms of Pipeworx tools/packs' and 'don't paste the end-user's prompt' enriches message/context semantics. It also aligns type options with use-case triggers.

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?

Specific verb+resource ('Tell the Pipeworx team') and enumerates feedback types (bug, feature, data_gap, praise), distinguishing it from sibling tools like ask_pipeworx and suggest_questions.

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 scenarios (bug, feature/data_gap, praise) and a when-not (don't paste end-user's prompt), but doesn't name alternative tools explicitly, leaving 'use the actual tool if it exists' implicit.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds behavioral detail: data source ('CF analytics-engine'), no PII, caching window ('5min-1h'), and the aggregated shape ('(pack, tool, count)'). This goes beyond the structured hints.

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

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

Description is well-structured and front-loaded with the core purpose, then adds a concise list of use cases and a brief note on data provenance/caching. No filler, but slightly long with the numbered list.

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

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

For a simple read-only tool with one optional parameter, the description covers outputs, use cases, and behavioral nuances (caching, PII). The absence of an output schema is mitigated by describing the shape of the aggregated data.

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 fully documents the single `window` parameter with enum values and a description explaining the trade-off. The tool description mentions the window options but does not add meaningful semantics beyond what the schema provides, so baseline 3 applies.

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

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

Description opens with a clear, specific statement: 'What other AI agents are calling on Pipeworx right now' and specifies outputs ('top tools, top packs, total call volume') and window options. This distinguishes it from sibling tools like discover_tools by focusing on aggregate trending signal rather than discovery.

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

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

Provides explicit 'Useful for' list with three concrete scenarios (hot data sources, canonical tool confirmation, alignment check), making when-to-use clear. Does not mention alternative tools or when-not-to-use, so not a full 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 the tool read-only, open-world, idempotent, and non-destructive. The description greatly expands on this by detailing specific behavioral internals: the >3pp threshold for partition deviations, placeholder filtering, the fill check against live CLOB depth, and clear warnings like 'do not trade it' when realizable edge is non-positive. 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 every sentence adds unique, actionable information. It is logically structured into sections (modes, semantic anchor, partition filter, response format, fill check) and front-loads the core purpose. No redundant phrases or filler. 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?

Given the tool has no output schema, the description fully defines the response structure: opportunities[] with specific fields, and the partition_check object in event mode. It also covers edge cases (placeholder slugs, low similarity, thin legs) and tells the agent exactly when to avoid trading. This is remarkably complete for a complex tool.

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

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

Although the input schema already provides 100% coverage of both parameters, the description adds rich semantics beyond the schema: it explains the no-arg trending_scan mode, gives exact slug/seed examples, details what each mode does internally, and clarifies constraints like the Jaccard similarity and placeholder fraction. This far exceeds baseline schema coverage.

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

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

The description opens with a specific, unambiguous statement: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly names the tool's function, its method, and distinguishes it from siblings like polymarket_edges by focusing on arbitrage via these checks. The two modes (event and topic) are explicitly defined, so the purpose is 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 explicit guidance on when to call with no args, when to use `event`, and when to use `topic`, including concrete examples. It also notes the limitation of single-event mode and the benefit of cross-event mode, and directs custom sizing to a sibling tool (`polymarket_fill_risk`). This is exemplary usage guidance.

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

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

The description extensively discloses internal logic: the five model families, response segments, filters, diagnostic counters, caching behavior, and edge calculations (edge_pp_net, Kelly caps). This goes far beyond the annotations (readOnly, idempotent) and tells the agent exactly what to expect in the output, including warnings like 'Market moved X.Xpp in 24h.'

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 very long and dense, but well-structured with numbered model families and parenthetical clarifications. It front-loads the primary purpose but then goes into deep detail that may be more than needed for selection. Every sentence contributes useful information, but it is not concise.

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 analytical tool with 9 parameters and no output schema, the description covers response shape (by_segment, fed_candidates, _diagnostics), the meaning of edge fields, knob effects, and caching behavior. It is fully self-contained and more than sufficient for an agent to invoke and interpret results.

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

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

With 100% schema coverage, the schema already documents all parameters. The description adds contextual meaning for key knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly), explaining their behavioral effect on filtering and their interaction with model logic (e.g., min_kelly does not filter partition arbs). This is meaningful added value, though it doesn't walk through every 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 opens with a specific verb+resource ('Scan top Polymarket markets...') and states the output (opportunities where Pipeworx data disagrees with market price). It also frames the use case ('what should I bet on today'), which clearly distinguishes it from generic market-listing or arbitrage tools among the siblings.

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

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

Explicitly states when to use it ('Built for "what should I bet on today"') and that it avoids paging hundreds of markets. It also explains why Fed bets are excluded from ranking, providing context. However, it does not explicitly name alternative tools for cases where a different tool would be more suitable.

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, but the description significantly adds behavioral context: snapshot gaps mean nobody scanned that day, history is bounded by a 60-day TTL, and decay is computed on daily closes net of slippage. It also clearly explains the difference between tracked and expired opportunities, covering edge cases and limitations beyond annotation signals.

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, starting with purpose, then parameters, then a detailed response breakdown, and then limitations. It is information-dense and mostly front-loaded. A minor deduction for repeating schema details (e.g., defaults and parameter names) that are already present in the input schema.

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

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

With no output schema, the description fully compensates by detailing the response shape: tracked[] with trend types and decay_pp_per_day, expired[] with lifespan_days, and snapshot_dates[] with gap meaning. It also covers history-depth limits and computational basis. This is highly complete for a read-only telemetry tool.

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

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

Schema coverage is 100% (both parameters have descriptions), so the baseline is 3. The description restates parameter defaults ('days (lookback, default 14, max 30)', 'window (snapshot family, default "1wk")') and adds the term 'snapshot family' but does not provide substantial new semantics beyond the schema. It earns the baseline but does not exceed it.

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

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

The description clearly identifies the tool as 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and further specifies its function by answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from the sibling 'polymarket_edges' tool by focusing on persistence/decay rather than raw edge 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 explicit use-case context: it tells the agent this tool is for evaluating whether an edge is fresh or stale ('a fresh wide edge and a 3-week-old wide edge are different trades'). However, it does not explicitly state when not to use it or name alternative tools, so it falls just 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses behavior in detail: walks the ladder, returns specific fields, identifies 'thin_legs', and explains the risk of 'forced_directional_risk' and unhedged positions. It fully describes what happens without repeating annotation data.

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, with clear mode breakdowns (SINGLE-MARKET vs BASKET), explicit return fields, and a final usage guideline. Every sentence adds value; length is justified by complexity. Front-loaded with the core purpose.

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 output schema, the description enumerates all key return fields for both modes, plus risk factors and threshold guidance. It covers the full workflow from input to interpretation, making it self-contained for an agent to invoke and expect outputs.

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

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

The schema already covers 100% of parameters, but the description adds essential contextual semantics: for 'side' it explains the basket mode auto-default based on partition sum, and for 'size_usd' it clarifies buy max-spend vs sell target-proceeds and basket settlement notional. This goes beyond the schema's literal definitions.

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

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

The description opens with a precise definition: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly contrasts with sibling tools and uniquely explains the tool's role as a pre-trade check, naming specific return metrics and modes. This is a specific verb+resource with clear 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 explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also distinguishes between single-market and basket modes, and explains why partial fills are dangerous. Clear and actionable guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds significant context beyond that: explains compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs 0), temporal_alignment and its implications for meaningful spreads, skipped_cross_type/subtype counters, and the honest caveat that pre-mapped topics are not necessarily tradeable. No contradictions with annotations.

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

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

The description is long but entirely purposeful. It front-loads the core purpose, then systematically covers modes, response format, safety fields, and real-world caveats. Every sentence contributes new information, and the structure uses clear labels (TWO MODES, RESPONSE, SAFETY FIELDS) that make it easy to scan. Despite its length, it remains efficiently organized.

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 the return structure. It does so thoroughly: leg-by-leg prices, matched spread[].top_spreads_pp, and detailed explanations of compatibility_warning and temporal_alignment. Given the tool's complexity, the description fully covers what the agent needs to understand inputs, outputs, and failure modes.

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

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

The input schema provides 100% coverage for parameter descriptions, so baseline is 3. The description adds semantic value by explaining the two modes: topic auto-fetches from pre-mapped shortcuts, while kalshi_event_ticker and polymarket_event_slug override the mapped sides for custom pairings. This contextualizes how the parameters relate to each other, which is not evident from the schema alone.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the specific verb (cross-venue spread) and resource (Kalshi/Polymarket), and distinguishes it from siblings like polymarket_arbitrage or polymarket_edges by focusing on the same-event, leg-by-leg comparison. The two modes (topic and explicit) are also clearly outlined.

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 when-to-use context: comparing a resolving question across Kalshi and Polymarket. It warns about limitations ('most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable') and explains the significance of compatibility_warning. However, it does not explicitly mention alternative tools or exclusions when another tool would be preferable, which would elevate it to 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, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context beyond the annotations, such as scoping to the identifier (anonymous IP, BYO key hash, account ID) and the list-all-keys behavior when the key is omitted.

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

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

The description is compact and front-loaded. It starts with the primary action, then gives use cases, then scoping and pairing notes. Every sentence earns its place, with no redundant phrasing.

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

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

For a simple one-optional-parameter tool with strong annotations and full schema coverage, the description covers essential aspects: how to retrieve, how to list, scope, and relationship to sibling tools. It does not describe the return format, but the output schema is absent and the tool's simplicity makes that less critical.

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 illustrating what kinds of keys might be stored (target ticker, address, research notes), which helps the agent understand the semantic range of the 'key' parameter beyond the generic schema definition.

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

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

The description clearly states the tool retrieves a previously saved value or lists all keys, with specific verbs and resources. It explicitly distinguishes itself from sibling tools by mentioning pairing with 'remember' to save and 'forget' to delete.

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

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

The description provides clear context for when to use the tool ('Use to look up context the agent stored earlier') and gives concrete examples. It also explains the optional key argument behavior (omit to list all keys). It does not explicitly name alternative tools for exclusion, but the use-case guidance is sufficiently clear.

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

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

The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones.' This is a state mutation (marking events as read) that contradicts readOnlyHint. Even though mark_read is optional, the tool is not strictly read-only, and the description does not reconcile this with 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 compact (three sentences) and front-loaded with the core action. The first sentence states what the tool does; the second details the return format; the third covers filtering, mark_read behavior, and an alternative endpoint. Every sentence adds value with no redundancy or filler.

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

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

Despite the absence of an output schema, the description explicitly describes the return fields (source, citation_uri, raw event payload). It also covers filtering, the mark_read side effect, and polling behavior. Combined with full parameter documentation in the schema, an agent has enough context to decide when and how to invoke this tool, aside from the read-only contradiction noted earlier.

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 all 5 parameters, so the baseline is 3. The description adds meaningful context beyond the schema by providing a concrete type example ('sec_8k'), clarifying the 'since' parameter as ISO timestamp, and explaining the effect of mark_read ('next call only shows newer ones'). This enriches the agent's understanding of these parameters without repeating the schema verbatim.

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 that clearly distinguishes it from siblings like list_subscriptions (which lists subscriptions) and recent_changes. It also describes the return payload (source, citation_uri, raw event payload), leaving no ambiguity about the tool's purpose.

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

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

The description provides clear context for when to use the tool: it is for pulling fired events, supports filtering by type and since, and mentions that 'Polls work fine.' It also points to an alternative for scripts/dashboards (GET registry.pipeworx.io/alerts.json). However, it does not explicitly name sibling MCP tools as alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds substantial behavioral context: it fans out to multiple external APIs in parallel, uses a GDELT→GNews fallback on rate limits/5xx, and notes that USPTO data soft-fails until the PatentsView API is reactivated. This goes well beyond the annotations' safety profile.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose with example user intents, then systematically covers the data sources, fallback behavior, parameter formats, return structure, and the alternative tool. Despite its length, it remains organized and readable without repetition.

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

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

Given the tool's complexity (multiple sources, fallback logic, failure conditions) and the absence of an output schema, the description fully compensates by explaining the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also covers edge cases like USPTO soft-failure, making it complete for an agent to understand expected 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%, but the description enriches the parameters meaningfully: it explains `since` accepts ISO dates or relative shorthand, provides examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and clarifies that `value` can be a ticker or zero-padded CIK. This is added semantic value 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 clearly identifies the tool as a change feed for a company over a time window, with a specific verb and resource ('change feed'). It distinguishes from sibling tools by explicitly naming entity_profile as the alternative for static profiles, and by listing the specific sources (SEC EDGAR, GDELT/GNews, USPTO) that uniquely define this tool's scope.

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

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

The description provides detailed guidance on when to use the tool (e.g., queries like 'what's new with X' and 'updates on Acme') and explicitly contrasts it with entity_profile for static profile needs. It also explains the fallback behavior between GDELT and GNews, and the soft-failure condition for USPTO, giving clear context for when the tool behaves differently.

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 provide idempotentHint=true and readOnlyHint=false, but the description adds valuable behavioral context: persistence semantics (authenticated vs anonymous session TTL), scoping by identifier, and the key-value storage model. It does not explicitly mention overwriting behavior, but the idempotent hint partially covers that. Overall, it exceeds baseline but is not exhaustive.

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 efficient and front-loaded: first sentence defines purpose, then usage triggers, then implementation detail, then related tools. Every sentence carries distinct information, and the overall length is proportionate to the tool's simplicity.

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 write tool with no output schema and fully documented parameters, the description covers purpose, usage, persistence behavior, and tool relationships. It provides sufficient context for an agent to invoke it correctly without any 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 100%, so the schema already fully explains both parameters. The description does not add parameter-specific meaning beyond what the schema provides; it merely reiterates that data is stored as key-value pairs. Baseline score of 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' using a specific verb ('Save') and resource ('data... key-value pair'). It distinguishes itself from siblings by explicitly referencing 'recall' and 'forget' as complementary tools, thereby positioning this as the write operation.

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

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

Explicitly states when to use: 'Use when you discover something worth carrying forward' with concrete examples. It also names alternatives and complementary tools: 'Pair with recall to retrieve later, forget to delete.' This provides clear when and with-what guidance, fully meeting the criteria for explicit 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 read-only, idempotent, and open-world behavior. The description goes further by disclosing internal cascading through lookup endpoints, exact return fields (ticker, CIK, RxCUI, ingredient, brand), citation URIs, and auto-disambiguation behavior. This adds substantial context 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 thorough yet efficient. It front-loads the purpose with illustrative examples, then breaks down each supported type, input formats, and outputs, and ends with a performance note. Every sentence contributes valuable information with no repetition 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?

Given the tool's complexity (two entity types with distinct outputs) and no output schema, the description fully explains return values for each type, including citation URIs. It also sets expectations by noting the internal cascading and efficiency gain. This provides a complete picture for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% coverage with descriptions and examples for both parameters. The description reinforces these formats (e.g., ticker, CIK, name) and mentions auto-disambiguation, but does not add significant syntax or format details beyond what the schema already contains. 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 and specifically states the tool's purpose: resolving user-spoken names to canonical identifiers. It provides concrete example queries and enumerates the exact entity types and return values, distinguishing it from sibling tools that focus on profiles or comparisons.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear directive on when to use it. It mentions that it replaces 2-3 manual lookups, but does not name specific alternatives or state when not to use it. Still, the guidance is strong and practical.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density, which goes beyond the annotations. It does not mention potential external API costs or rate limits, but given the strong annotation coverage and read-only nature, a 4 is appropriate.

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 main action, then the method, then the use case and return format. Every sentence provides necessary information without redundancy or fluff. It is well-structured and appropriately sized for the tool's complexity.

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

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

Given the tool has 4 parameters, no output schema, and relies on external probes, the description is complete: it explains the purpose, method (probes with ai_visibility_check), output (ranked list with score, confidence, signal density), and a real-world use case. It does not need to repeat schema details like entity count limits or model options, making it sufficient for an agent to select and understand the tool.

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

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

Schema coverage is 100% (all parameters have descriptions). The description adds context by explaining the entities parameter as 'your brand + N competitors', which clarifies that the first entry should be the user's own brand. This is a small but valuable semantic addition beyond the schema's generic 'subject' wording. The schema already covers models and _apiKey, so no further params need explanation.

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.' It uses specific verbs ('probes', 'ranks', 'surfaces') and identifies the resource (AI visibility via ai_visibility_check). It distinguishes from sibling ai_visibility_check by focusing on multi-entity comparison.

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: 'Useful for competitive AI-marketing audits: "does Claude know about us as well as our competitors?"'. This clearly implies when to use it, and the mention of probing with ai_visibility_check indirectly references the single-entity alternative. However, it does not explicitly state when not to use it or name an alternative 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed will report timeouts, and the rest still returns. It also discloses ecosystem limitations, going 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 fairly long but every sentence carries essential information about the composite nature, return block, failure modes, and ecosystem scope. It is efficiently structured with dashes separating key points, though it could benefit from newlines for even better scanability.

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 return values (summary block fields, per-advisory detail, links, recent alternatives), failure behavior, and timeouts. It also addresses system constraints (NPM-only, timing) and sets expectations for partial failures, 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 description coverage is 100% for both parameters; the description adds no new parameter-specific meaning beyond what the schema already provides. It merely echoes the defaults and scoped-package acceptance, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool is a composite 'should I add this npm package' check that fans out across deps.dev and bundlephobia. It specifies the verb ('scan', 'check'), the resource (npm package), and the scope (safety, popularity, size), distinguishing it from sibling tools like bet_research or validate_claim.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and provides an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives clear when-to-use and when-not-to-use guidance.

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

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

The description discloses substantial behavioral details: it returns passages with character offsets and similarity scores, uses BGE-base-en embeddings over 500-char windows, and truncates inputs over 200K chars with a flag. These go well beyond the readOnlyHint/idempotentHint annotations and help the agent predict outputs and side effects.

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

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

The description is efficiently structured, with each sentence adding distinct information: core function, output format, use case, pairing, and technical limits. It front-loads the core action and remains free of redundancy despite covering multiple aspects.

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

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

With no output schema, the description adequately explains the return format (passages with offsets and similarity scores), as well as usage context and truncation behavior. It also positions the tool among siblings, making it complete for an agent to select and invoke correctly.

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

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

The input schema already covers all three parameters with descriptions and examples, achieving 100% coverage. The prose description adds some context (e.g., 'text you already pulled') but does not materially exceed what the schema already provides, 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 opens with 'Semantic search INSIDE a fetched record,' which is a specific verb+resource pairing. It further distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and noting it searches inside already-fetched text rather than performing a broader query.

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 states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative/complement workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This is clear actionable 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 adds substantial behavioral context beyond the annotations: it requires an OAuth account, explicitly states that anonymous and BYO users cannot persist subscriptions, returns a subscription id, explains the feed delivery mechanism, and details SMS verification and daily caps. This goes well beyond the basic readOnly/idempotent/destructive hints. No contradictions with annotations.

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

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

The description is information-dense but well-front-loaded with the core purpose. Every sentence adds value: types, examples, delivery channels, and limitations. It is a single paragraph with effective use of dashes and examples, but slightly long; still, it avoids redundancy and 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?

For a tool with nested objects and multiple types, the description covers prerequisites, type-specific params, delivery options, and operational caveats (verification, caps). It does not explain the full response shape beyond the subscription id, but no output schema exists, so the description provides sufficient decision-making information. Missing error scenarios, but overall 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 description coverage is 100%, so baseline is 3. The description adds meaningful semantics by providing concrete examples for each subscription type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and elaborates the always-on feed, which is not explicitly in the schema as a default channel. It also mentions retrieval via recent_alerts, adding context beyond the raw schema.

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

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

The description uses a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of a subscription. The supported types and delivery channels make the purpose unambiguous.

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

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

The description provides clear context on when to use the tool: when setting up recurring monitoring on live data. It also mentions prerequisites (Pipeworx OAuth account) and the always-on feed as a baseline, with optional email/sms channels. However, it does not explicitly compare against alternative sibling tools (e.g., list_subscriptions, unsubscribe) or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond this by stating it returns category-bucketed example questions with exact tool/argument shapes drawn from a live catalog, and that calling with no arguments yields a cross-category spread. This helps the agent predict the output shape and behavior without overexplaining.

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. Every clause earns its place: it lists multiple user intents, describes the output structure, and provides usage instructions. It is front-loaded with common questions, though the heavy use of dashes creates a run-on feel that could be slightly better structured.

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

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

For a simple tool with one optional parameter and no output schema, the description sufficiently explains what it returns (category-bucketed example questions with tool/argument shape), when to call it, and how to use the topic parameter. It covers the essential information an agent needs without requiring an output schema.

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

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

The schema already covers the parameter with a description listing valid focus areas. The description adds behavioral nuance by explaining that omitting the topic gives a cross-category spread, while passing a topic like 'finance' or 'pharma' narrows the results. This goes beyond the schema's simple listing and clarifies the parameter's effect on output.

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

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

The description names a specific purpose: onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape to answer them. It clearly differentiates from siblings by positioning it as the 'first' tool to use when unfamiliar with Pipeworx, and it references meta-tools like ask_pipeworx and entity_profile, distinguishing it from more specialized 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 gives clear when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to choose between no arguments (full spread) and passing a topic to focus, though it does not explicitly name alternative tools to use after gaining context, which keeps it just below a perfect score.

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

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

Annotations already indicate write, non-destructive, idempotent, and open-world behavior. The description goes further by disclosing ownership enforcement and the deactivation (soft-delete) mechanism, clarifying that historical events remain available via recent_alerts. This adds valuable behavioral 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 three concise sentences: action, ownership constraint, and consequence. It is front-loaded and free of unnecessary detail.

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

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

Given a simple mutation tool with one parameter, good annotations, and no output schema, the description covers the purpose, constraint, and side effect. It references recent_alerts for historical data. It omits error cases and return values, but those are not critical here.

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 100% coverage of the single parameter, describing it as a UUID returned by subscribe. The description adds the ownership requirement ('you can only cancel your own subscriptions'), which is a meaningful semantic constraint on the id 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 states 'Cancel a subscription by id' using a specific verb and resource, clearly differentiating it from related tools like subscribe, list_subscriptions, and recent_alerts. The scope is unambiguous.

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

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

The description provides clear context: ownership is enforced, so the tool should only be used for your own subscriptions. It also notes that the row is deactivated rather than deleted, implying the alternative recent_alerts for historical data. It does not explicitly mention when not to use it or name alternative tools, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: the automatic routing between SEC EDGAR/XBRL for company financials and grounded pipeline for other claims, plus the return of verdict types, citations, and reasoning. No contradiction with annotations.

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

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

The description is dense but efficient, front-loading with user phrasings to quickly orient the agent. Every sentence adds value: the two-path routing, the return value structure, and the replacement of sequential calls. 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?

With no output schema, the description compensates by explicitly enumerating the return fields (verdict, actual value, citation, reasoning) and describing the processing flow. It covers the main execution paths and edge conditions (tolerance override). Minor omissions like timeouts or failure modes are acceptable given the tool's complexity and annotations.

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 parameters are documented in the schema. The description enriches the tolerance_pct parameter by explaining its default behavior (implied by wording, capped at 5) and its use for hallucination detection (set 1–2), which goes beyond the schema's basic description. The claim parameter is illustrated with concrete examples.

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 validates natural-language factual claims against authoritative sources, with explicit verbs like 'verify', 'fact check', and 'confirm or refute'. It distinguishes between company-financial claims (SEd EDGAR fast path) and all other claims (grounded pipeline), which differentiates it from siblings and explains its unique scope.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides example phrasings. It also mentions replacing 4–6 sequential calls, implying when it's the right tool, though it doesn't name specific alternative tools or explicit 'when not to use' scenarios.

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