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 cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful non-inferable behavior: it routes the question across many tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict 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 front-loaded with the most important instruction ('PREFER OVER WEB SEARCH'), followed by a domain list, behavior explanation, trigger phrases, and examples. Each sentence earns its place and the structure makes the tool easy to select and invoke.

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 the input style, the routing behavior, the output format, and representative use cases, which is enough for an agent to invoke it correctly. It is not a 5 because it does not mention the relationship with ask_pipeworx_beta or ask_pipeworx_grounded, and does not disclose any failure or fallback behavior.

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

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

Schema coverage is 100%, so the schema already documents the aliases for the question parameter. The description adds extra semantic value by specifying the kinds of inputs to give it — natural-language factual questions, current or historical data requests, and concrete example queries.

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

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

The description clearly states that the tool answers factual questions by routing to authoritative structured-data tools and returns cited answers, which goes well beyond the title. However, it does not differentiate itself from the direct sibling tools ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description gives strong guidance: prefer this over web search, use trigger phrases like 'what is' or 'get the latest', and start here for most factual questions. It also supplies concrete examples. It does not explicitly state when not to use it or how it compares against ask_pipeworx_beta and ask_pipeworx_grounded, so it falls short of a perfect 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?

Even though annotations already mark it read-only, idempotent, and non-destructive, the description adds rich behavioral context: it is experimental, candidates are tested live, none is active right now, and it falls back to nothing because it is a full working router itself. This explains exactly what an agent should expect without contradicting 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 front-loaded with the most important identity and behavioral facts, and each sentence contributes distinct information. The date and 'outcome evidence' detail add some maintenance history that is not strictly needed for selecting or invoking the tool, keeping it just short of perfect conciseness.

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

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

The description covers what the tool is, how to use it, what it currently does, and what it does not fall back to. Since there is no output schema, the explicit 'same response shape' line is especially valuable. Given annotations, no critical operational context is missing.

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

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

Schema description coverage is 100%, and the schema already documents question plus its aliases. The description only says 'same arguments' as ask_pipeworx, which does not add meaning beyond the schema. This is the appropriate baseline because the schema carries the parameter documentation burden.

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 this as the beta version of ask_pipeworx and as the same universal router with the same tools, arguments, and response shape. It also distinguishes it from its stable sibling by its experimental, candidate-routing purpose. The agent knows what the tool is and how it differs from ask_pipeworx.

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 is explicit: use it like ask_pipeworx when you want the newest routing behavior, and results are compared against the stable router. It also notes that no candidate is currently active, so the current behavior matches ask_pipeworx exactly. This significantly reduces selection and invocation uncertainty.

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

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

The description goes far beyond the annotations by explaining the refusal behavior, refusal reasons, exact return shape with evidence and confidence fields, and the trade-off of an extra LLM call. It also clarifies the 'only what the tool result contains' guarantee, which is especially important for high-stakes use. The described behavior is consistent with the readOnly, idempotent, non-destructive annotations.

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

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

The description is dense but well-organized: it front-loads the core concept, then the return shape, then the usage rules, then the cost trade-off. Every sentence carries informational value, including refusal reasons and sibling comparison, without redundant filler. It is appropriately sized for a tool with multiple behavioral nuances.

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

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

There is no output schema, so the description explicitly enumerates the success response and failure refusal structure, which is essential. It also covers routing behavior, hallucination resistance, cost, and alternatives. With the schema handling parameters and annotations handling safety, the description supplies all remaining context an agent needs to invoke this 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 schema already covers all six parameters with 100% coverage, and every parameter is documented as an alias for 'question' and described as accepting natural language. The description reinforces that a natural-language question is the input but does not add new semantics about the parameters beyond what appears in the schema. A baseline 3 is appropriate because the schema fully handles parameter clarity.

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

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

The description states a specific function: a hallucination-resistant grounded answer mode that extracts answers only from tool results. It explicitly names the sibling ask_pipeworx to differentiate the grounded mode and introduces refusal mechanics with structured reason codes, making the tool's purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also provides an exclusion and alternative: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost. This fully directs the agent to choose the intended tool over 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 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 already mark it read-only, open-world, and idempotent; the description adds substantial behavioral context: account/paid-tier requirements, parallel tool routing, explicit gaps[] for unanswerable facets, citation_uri fetchability guarantees, hop semantics, contradiction flags for standard/thorough, and latency ranges. No contradictions with the annotations exist.

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

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

The description is long and dense, but it front-loads the most decision-relevant information: account requirements, alternative pick, and core identifying behavior. All sentences contain either advisory or behavioral value; a few repeated references to ask_pipeworx and depth behavior could be trimmed without loss, but the structure is not bloated 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?

There is no output schema, yet the description fully covers return-value semantics: findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also includes latency expectations and depth/iteration behavior, so an agent has essentially everything needed to invoke and interpret 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 covers both parameters well, and the description goes beyond it by giving concrete question examples and by clarifying how depth levels affect hop count, gap recovery, contradiction checks, and latency. This enriches the schema's baseline meaning for an agent selecting depth.

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

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

The description states a specific verb-resource pair: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources' with clear mechanics (decomposition, parallel routing, structured findings packet). It also explicitly contrasts itself with open-web search and sibling tools like ask_pipeworx, making the tool's role 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 gives explicit when-to-use guidance ('best for broad/multi-part questions over structured data'), explicit exclusions ('For a single lookup use ask_pipeworx instead'), and conditional direction ('If you are not signed in, use ask_pipeworx'). It even warns that breaking/current-narrative topics will mostly return empty gaps and belong to ask_pipeworx.

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

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

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 and offer no safety insight, so the description carries full burden. It discloses key behaviors: anonymous filing returns a claim_token for later lookup, rate-limited to 5 per identifier per day, free and not counted against tool-call quota. These go beyond the schema and are valuable for the agent.

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

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

The description is longer than average but every segment earns its place: purpose, usage conditions, exclusions, claim_token flow, rate limit, quota impact. It is front-loaded with the core purpose and uses clear structural cues. Slightly verbose, but justified given the complexity.

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

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

No output schema exists, so the description compensates by explaining what the tool returns (a claim_token) and how to read the status later. It covers scope, rate limits, quota policy, and how to reference Pipeworx tools. For a feedback tool, this is complete and self-sufficient.

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 operational meaning beyond the schema by explaining the claim_token round-trip ('Filing without an account returns a claim_token; pass it back later...') and a parameter-level constraint (rate limit). This supplements the already-detailed schema without repetition.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines what the tool does and distinguishes itself from sibling tools like ask_pipeworx by scoping to feedback about the Pipeworx connection's own tools.

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

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

Provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' Also gives an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is model behavior.

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?

The description adds substantial behavioral details beyond the annotations: graceful degradation ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), internal cascading ('Each call cascades through several lookup endpoints internally'), and explicit handling of unresolved identifiers ('an identifier that could NOT be resolved is stated explicitly under `unresolved`'). These enrich the agent's understanding of the tool's behavior, and no contradictions with annotations exist.

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

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

The description is fairly long but well-structured: starts with example queries, then a clear directive, then a detailed breakdown of supported types with bullet-like formatting. Every sentence adds value; no fluff. It could be slightly more concise but the density of useful information justifies the length.

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

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

Given the absence of an output schema, the description does a good job describing the return content: identifiers with sources, unresolved fields, specific ID types for company (CIK, ticker, LEI, FIGI) and drug (RxCUI, ingredient). It also mentions ownership data for LEI. It does not specify the exact JSON structure or keys, but the context of sibling tools (e.g., entity_profile) suggests this is a resolver returning identifiers, not profiles. The description is fairly complete for the tool's role.

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 significantly adds meaning: for the 'type' parameter, it lists concrete examples ('company', 'drug') with detailed explanations of what each returns. For the 'value' parameter, it provides exhaustive input forms (ticker, CIK, ISIN, company name ; brand or generic name) and even notes special behavior like ISIN-to-LEI mapping. This goes well beyond the schema's minimal 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 starts with clear example query patterns (e.g., 'What's the ticker for…', 'find the CIK for…'), then explicitly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also distinguishes itself by saying 'Use FIRST whenever you have a name but need an ID,' which clearly separates it from sibling tools like entity_profile or search 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 advises 'Use FIRST whenever you have a name but need an ID,' providing a clear when-to-use directive. While it does not explicitly list when NOT to use it or name alternative tools, the context of the sibling list and the tool's purpose strongly imply that if an ID is already known, a different tool (e.g., entity_profile) should be used. The guidance is strong but lacks explicit exclusion rules.

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 signal a safe, read-only, idempotent operation, and the description adds substantial behavioral detail: verdict categories, the SEC EDGAR/XBRL fast path for financial claims, automatic fallthrough for other claims, and the important caveat that could_not_verify means the check did not happen. This goes well beyond the structured annotations.

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

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

The description is longer than average but front-loaded with trigger phrases and pragmatic usage guidance. It is structured into clear sections and the 'IMPORTANT for callers' note is high-value, though some phrasing is verbose and could be trimmed without losing meaning.

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

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

With no output schema, the description compensates by explaining the return verdicts, grounded/structured actual value with citations, and reasoning. It also fully covers failure semantics (could_not_verify vs unsupported) and routing behavior for financial vs non-financial claims, making it complete enough for an agent to invoke and interpret results correctly.

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

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

The input schema already provides full coverage of both parameters, including a claim example and tolerance_pct with range, default, and intent. The description adds no new parameter-level syntax but reinforces the tolerance concept with 'exact percent-delta math'; since schema coverage is 100%, baseline 3 is appropriate.

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

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

The description clearly identifies the tool as claim verification, opening with natural-language trigger phrases and stating it verifies factual claims against authoritative sources. It distinguishes the tool from siblings by describing a specific financial-claim fast path and a grounded pipeline for all other claims, and it notes it replaces 4–6 sequential calls.

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

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

The description explicitly says to use it whenever the agent needs to check whether something a user said is factually correct, giving clear context. It does not name alternative tools or state when not to use this tool, but the trigger phrases and the note about replacing sequential calls provide practical guidance.

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