Ecb

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds critical behavioral details: default model is free, Anthropic requires BYO key and direct payment, and the return structure includes per-model scores. 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 a single paragraph that efficiently conveys the core action and key details. It is front-loaded with the main purpose. Could be slightly more structured (e.g., bullet points for return format), but it is not verbose and earns its place.

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

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

Given the tool complexity (4 parameters, no output schema), the description covers purpose, models, key, context, and return shape. It provides sufficient context for an agent to use the tool effectively, though an explicit output schema would reduce reliance on the description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model behavior for 'models' and the purpose of '_apiKey' and 'context'. This helps an agent understand parameter semantics beyond type constraints.

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: probing LLMs for knowledge about an entity and scoring visibility. It specifies the default model, the option to add Anthropic, and the return format. This distinguishes it from sibling tools like ask_pipeworx or deep_research, which are for general QA or research.

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

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

The description provides usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool or compare it to alternatives, which would strengthen guidelines.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses internal routing behavior, argument filling, and the stable citation URI format of the return value. It also states the scope of coverage (real-world entities, events, numbers, authoritative data), which adds useful context without contradicting any annotation.

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

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

The description is long but front-loaded and sectioned: preference, behavior, triggers, examples, and alternatives are each identifiable. Some domain lists and the final news-routing sentence add length beyond the core need, so it doesn't earn a 5.

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 tells the agent what to expect (structured answer with pipeworx:// citation URIs), when to use it, what inputs to pass, and which alternatives to choose in specific cases. For an open-ended meta-tool, this is sufficient context to invoke it correctly.

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

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

Schema coverage is 100%, so the aliases are already documented, but the description enriches the question parameter semantics with trigger phrases and varied example queries such as 'current US unemployment rate' and 'adverse events for ozempic'. This gives an agent a much better sense of acceptable natural-language inputs.

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

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

The description clearly identifies the tool as a natural-language router/answerer: it routes the question to one of 5,798 tools across 1,517 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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 to prefer this tool over web search and lists triggering phrasings ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') plus concrete examples. It also gives when-not conditions: use ask_pipeworx_grounded for a single answer with one argument and deep_research for broad/multi-part fan-out questions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behavioral nuance: candidate routing improvements can be switched on live, none are active right now, it is a full working router, and it falls back to nothing. This is exactly the kind of experimental status an agent needs before invoking.

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 identity in the first sentence and each later sentence adds status or usage information. It is slightly longer than strictly necessary, with some repetition between 'identical' and 'matches exactly,' but no sentence is wasted.

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 1-required-parameter tool with rich annotations, the description covers what the tool is, its current experimental state, when to prefer it, that it has no fallback, and that it matches the stable router's interface. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already explains the single required question parameter and all five aliases. The description adds no parameter-specific meaning, so the baseline 3 applies because the schema carries the 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 the tool as a beta universal router with the same 5,798 tools, arguments, and response shape as ask_pipeworx, immediately separating it from the stable sibling. It also specifies the experimental edge, so an agent understands what this tool is and how it differs.

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 to use it exactly like ask_pipeworx when the newest routing is desired and explains that results are compared with the stable router to decide merges. The current no-active-candidate state is disclosed, which tells the agent when behavior is identical to the stable version.

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

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

Beyond the read-only and idempotent annotations, the description discloses the refusal behavior with enumerated refusal_reason values, the constraint that evidence is a verbatim quote, and the cost of one extra LLM call. It also clarifies that extraction uses 'ONLY what the tool result contains,' setting clear expectations about hallucination resistance. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing mechanism, return shape, refusal reasons, use cases, and cost comparison. It is front-loaded with the defining trait (grounded, hallucination-resistant) and structured so an agent can quickly parse when and how to use it.

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 full burden of explaining return values and failure modes, and it does so thoroughly: success returns answer, evidence, confidence, source, fetched_at; failures return explicit refusal reasons. It also covers applicability for high-stakes domains and the cost comparison, making the tool fully understandable 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 description coverage is 100%, and the schema already documents the question parameter with its aliases and natural-language expectation. The description adds context that the question drives routing and fetching, but no additional parameter syntax or formatting details. Baseline 3 is appropriate given the 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 defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its exact flow: routing, fetching, and extracting answers only from tool results. It also distinguishes itself from ask_pipeworx by grounding answers and returning refusals when data doesn't directly answer, making sibling differentiation immediate.

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 this tool: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It names the alternative (ask_pipeworx) and even quantifies the trade-off with the extra LLM call cost.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: market resolution, classification, parallel fan-out, response shapes, resolver contract, parent_event extraction, news fallback, safety shortcuts, and cancellation rule parsing. No contradictions.

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 detailed, including classifiers, fan-out examples, and response shapes. While well-structured with clear sections, it could be more concise. Some details may be excessive for a tool description.

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

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

Given no output schema, the description thoroughly covers response shapes, evidence structure, market fields, analysis, parent_event, news fields, safety, and cancellation rules. It is complete for understanding what the tool returns.

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

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

Schema covers 100% of parameters with descriptions. The description adds examples for 'market', explains 'depth' and 'include_raw' options, providing additional context beyond schema. Baseline 3, plus value for examples and usage guidance.

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 researches a Polymarket bet by pulling relevant data, with examples of input formats and use cases. It distinguishes itself from siblings by focusing on bet-specific research, though it doesn't explicitly contrast with siblings.

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

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

The description provides explicit use cases ('should I bet on X', etc.) and includes safety notes about low-confidence matches and closed markets. It lacks explicit exclusion of when not to use this tool versus 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 readOnly, openWorld, idempotent. Description adds critical behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, citation URIs, and efficiency gain (replaces 8–15 lookups). No contradiction.

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

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

Description is fairly long but each sentence adds value. Front-loaded with trigger phrases and examples. Could be slightly more concise, but structure is logical and effective.

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 2 params, no output schema, and rich annotations, the description fully covers use case, data sources, behavior, return format, and efficiency, leaving no gaps for the AI 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%, baseline 3. Description adds concrete examples for values (tickers/CIKs for company, drug names) and clarifies enum semantics, enhancing understanding beyond the schema.

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

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

Description explicitly states 'side-by-side comparison of 2–5 companies or drugs' and provides clear examples like 'compare X and Y', 'X vs Y'. It distinguishes from sequential single-entity lookups, making the 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?

Description gives explicit when-to-use trigger phrases ('which is bigger', 'rank these companies') and instructs ALWAYS PREFER over sequential lookups, providing clear context for tool selection.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent; the description adds account requirements, paid depth tier, parallel decomposition, response contents (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[]), non-hallucination behavior, semantic excerpting, and expected latency. This goes well beyond what annotations alone provide and is consistent with them.

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

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

The description contains abundant useful detail and is front-loaded with account prerequisites, but the central 'Grounded multi-source research...' passage is repeated nearly verbatim many times, making the text severely bloated and hard to parse. This repetition violates the expectation that every sentence earns its place.

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

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

Even without an output schema, the description explains the return packet format: evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], and contradictions[]. It also covers citation fetchability, excerpting behavior, auth, latency, and data-source boundaries, so an agent has enough context 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 already documents both parameters with 100% coverage, so the baseline is 3. The description adds meaningful depth semantics: what each depth value means in terms of facets, hops, gap recovery, and contradiction scanning, and it clarifies that the question should be natural language and may be broad or multi-part.

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 identifies a specific action and resource: grounded multi-source research across Pipeworx's 1,517 structured data sources in one call, with a clear negative boundary: 'this is NOT open-web search.' It also contrasts with ask_pipeworx for single lookups, so an agent can distinguish it from sibling tools without needing to open their schemas.

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 gives explicit when-to-use guidance: broad or multi-part questions over structured data, and explicit when-not-to-use guidance: single lookups should go to ask_pipeworx instead. It also adds auth routing: if not signed in, use ask_pipeworx because it works on every tier, and clarifies that the thorough depth requires a paid plan.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N most relevant tools with full input schemas and curated examples, and states that results are 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and fully discloses the tool's behavior.

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

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

The description is a single paragraph of 4 sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, when to use, what it returns, and a call to action. It is concise without any filler, wasting no 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?

Given the tool's complexity (6 parameters, all documented in schema) and no output schema, the description is complete. It covers the return format (top-N tools with schemas and examples), domains it covers, and usage advice. No gaps remain for an agent to understand what the tool does and how to use it.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds meaning by explaining the 'query' parameter is a 'Natural language description of what you want to do' and lists its aliases (task, q, description, search). It also provides examples in the schema. This adds value beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find/discover) and resource (tools), and distinguishes from sibling tools by emphasizing discovery and browsing, which is unique among the listed siblings.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists example domains (SEC filings, stocks, etc.), giving clear context on when to use it. This provides strong usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the rate is a published mid-market reference without bid/ask spread. It also specifies the return format (latest with period and value, plus recent observations). This goes beyond what annotations provide.

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

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

The description is succinct (3-4 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no redundant or verbose language.

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, but the description explains the return format adequately. It covers main use cases (current rate, historical series) and parameter roles. It could mention error handling or rate limits, but the provided information is sufficient for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default for last_n (30) and the purpose of start_period/end_period for history. This reduces ambiguity beyond the schema descriptions.

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

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

The description clearly identifies the tool as providing authoritative EUR reference rates from the ECB, listing example queries and target currencies. It differentiates from sibling tools like ecb_hicp_inflation and ecb_list_dataflows by explicitly focusing on exchange rates.

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

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

The description provides explicit use cases ('current EUR/USD rate', 'EURUSD spot', etc.) and explains how to retrieve historical data with start_period/end_period or last_n. It lacks explicit guidance on when not to use this tool or alternatives, but the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds minimal behavioral detail beyond the example usage, which is consistent with annotations.

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

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

Two sentences with a concise example, no wasted words. The information is front-loaded.

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

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

Given 5 parameters all described in schema and no output schema, the description provides sufficient context for typical usage, but could briefly mention the return format.

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

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

Schema coverage is 100%, but the description adds meaningful explanation of the key parameter (dot-separated, wildcards) and lists example flow_ref values, providing context beyond the schema.

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

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

The description clearly states 'Generic SDMX data fetch from any ECB flow', specifying the verb and resource. It distinguishes from siblings like ecb_exchange_rate and ecb_hicp_inflation which are specific tools.

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

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

The description provides an example and explains the key format, implying use for generic ECB data. However, it does not explicitly state when to use this tool versus specific siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds default country and frequency, but does not deepen behavioral understanding beyond annotations.

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

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

Single, well-structured sentence with key information (what, frequency, default) front-loaded. No wasted words.

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

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

For a simple read-only tool with three well-described parameters and no output schema, the description is sufficiently complete. Could optionally mention data format or limitations, but not required.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds only the default value for 'country', which is useful but not transformative. 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?

Description clearly states it retrieves the HICP annual rate of change for a country/euro area, with monthly frequency and default country. Distinguishes from sibling ECB 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?

No explicit when/when-not or alternative tool mention, but the name and description clearly indicate it is for HICP inflation data, making usage obvious.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior, lowering the burden on the description. The description adds useful behavioral detail beyond annotations: the filter is case-insensitive, can match flow_ref or name, and the exact return shape is disclosed. 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?

Three tightly packed sentences deliver purpose, filter semantics, and return format without wasted words. The output shape is included inline, and the most important cross-tool relationship is placed at the end for emphasis.

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

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

The tool has only one optional parameter, strong safety annotations, and no output schema. The description fully compensates for the missing output schema by spelling out the return object, and it connects flow_ref to ecb_get_data. Nothing needed for correct invocation is missing.

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

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

The schema already describes filter as a case-insensitive substring, which is 100% schema coverage. The description adds meaning by specifying that the filter applies to flow_ref or name, and by showing how the parameter result connects to ecb_get_data. This exceeds the baseline schema-only documentation.

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

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

The description opens with a specific verb and resource: 'List all ECB SDMX dataflow IDs and names' and gives concrete examples (EXR, ICP, BSI, MIR). It clearly distinguishes this tool from data-fetching siblings like ecb_get_data by framing flow_ref as an input to that tool.

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

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

The description makes the context clear: use this when you need to enumerate available ECB dataflows and obtain the flow_ref values. It references ecb_get_data as the downstream consumer, which implicitly guides routing, but it does not explicitly state when not to use it or compare it directly with siblings.

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 fan-out across sources, soft-failure of USPTO patents until May 2025, that empty sections are real 'no data', resolved:false behavior for private companies, and the interchangeable type semantics. This is rich behavioral context that annotations alone would not provide.

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

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

The description is dense but front-loaded with purpose and a usage rule before enumerating outputs. It is long because it documents many return sections, and some phrasing duplicates the schema, but nearly every detail serves a real purpose for a complex tool.

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

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

With no output schema, the description must carry the return-value burden, and it does: it lists each response section, explains sources_used/sources_failed semantics, expected empty results, and input resolution behavior. An agent has enough to invoke it correctly and interpret the response.

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%; the schema already documents that type accepts company/ticker and value accepts ticker, zero-padded CIK, or company name. The description repeats these facts rather than adding substantial new parameter semantics, so the baseline 3 applies.

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

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

The description opens with concrete user phrasings and states the tool builds a 'full cross-source profile of a US public company in ONE parallel call.' It defines the resource ('profile'), the scope (US public company), and positions itself as preferred over chaining single-pack lookups, so an agent knows what it is for even without opening the schema.

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 to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is a clear when-to-use signal. It also explains valid inputs and the private-company fallback. It does not name specific sibling tools or state when not to use this in favor of a related tool like deep_research, 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?

The description's 'Delete' aligns with annotations (destructiveHint=true), and adds context about sensitive data clearing. No contradictions, and it adds value beyond what annotations provide.

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

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

Two sentences: first states purpose, second gives usage guidelines. Extremely concise, front-loaded, and every sentence contributes meaningfully.

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

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

For a simple one-parameter destructive tool with annotations, the description is complete. It covers purpose, when to use, and references sibling tools, leaving no significant gaps.

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

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

Only one parameter (key) with 100% schema coverage. The description rephrases 'by key' but adds no new meaning beyond the schema's 'Memory key to delete', so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb (delete) and resource (memory by key). It effectively distinguishes itself from siblings remember and recall, which are also mentioned.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with remember and recall, offering context for appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms this with 'Fetches the page, extracts title/description/key links, and emits...' and adds context about the process. No contradictions. Could mention rate limits or error handling but not essential.

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

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

Two concise sentences plus a bullet list of use cases. Front-loaded with the primary action. No redundant or unclear phrases.

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 simple parameters, full annotations, and no output schema (but description states 'single text blob'), the description fully covers what the tool does, how it works, and when to use it. No 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 coverage is 100% with both parameters described. Description adds value by stating 'default 25, max 50' for max_links, which is not in the schema. This helps the agent set appropriate values.

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

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

Description clearly states the verb 'Generate' and the specific resource 'production-ready llms.txt file for any URL'. It distinguishes from siblings like 'scan_competitor_ai_presence' by being uniquely focused on llms.txt generation.

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?

Description lists clear use cases: getting a client's site indexed, drafting own project's llms.txt, auditing competitor indexing. While it doesn't explicitly state when not to use, the use cases imply applicability. No sibling tool overlaps enough to require exclusion.

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 behavioral context beyond annotations: it notes that only active subscriptions are returned by default (not cancelled) and lists the exact fields. The readOnlyHint and idempotentHint are already present, so the description complements them without contradiction.

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

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

The description is three sentences, front-loading the purpose and return fields, followed by a succinct usage guide. Every sentence adds value, no redundancy.

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

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

For a simple list tool with one optional parameter, the description covers the essential aspects: what it returns, when to use it, and how it behaves regarding active vs inactive. It is complete given the tool's complexity.

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

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

The only parameter (include_inactive) is fully described in the input schema (100% coverage). The tool description does not add additional meaning or usage context for this parameter beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List') and the resource ('caller's active subscriptions'), and lists the specific fields returned. This directly differentiates it from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool relative to subscribe/unsubscribe.

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

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

The description richly covers behavioral traits beyond annotations: it discloses the claim_token workflow, rate limiting ('Rate-limited to 5 per identifier per day'), quota implications ('doesn't count against your tool-call quota'), and how feedback is processed ('team reads digests daily'). This goes far beyond the sparse annotation hints.

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

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

The description is longer than typical but front-loaded with the core purpose. Each subsequent sentence adds essential information (scope, claim_token flow, rate limits), though it could be tightened slightly without losing value. The structure is logical: purpose → when-to-use → exclusions → workflow → constraints.

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

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

Given there is no output schema, the description compensates by explaining what the tool returns ('Filing without an account returns a `claim_token`') and how to later interpret status. It also covers the nested context object, type enum semantics, rate limits, and quota impact, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for the claim_token parameter (explaining the round-trip flow: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies how message should be phrased ('don't paste the end-user's prompt'), which enriches the schema's baseline 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 a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This unambiguously identifies the tool as a feedback mechanism and clearly differentiates it from siblings like ask_pipeworx or remember, which serve other 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?

The description gives explicit 'when to use' conditions for each feedback type ('Use when a tool returns wrong/stale data... or when something worked surprisingly well'), and explicitly excludes out-of-scope cases with 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This is an exemplary usage guideline.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: 'Self-aggregating signal — derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window.' This discloses data source, privacy, and caching behavior, adding significant value beyond annotations.

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

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

The description is well-structured with numbered use cases and concise sentences. Every sentence adds value, and there is no redundancy. The length is appropriate for the complexity of the 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?

Despite no output schema, the description explains the return: 'top tools, top packs, and total call volume.' It also mentions caching behavior. Given the tool's simplicity (single optional parameter), the description is complete and sufficient for an agent to invoke it correctly.

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

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

The schema already has 100% coverage with an enum and description. The description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides additional guidance for parameter selection, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: returns top tools, top packs, and total call volume. It lists three specific use cases, making it easy to understand when to use it. The description distinguishes this analytics tool from sibling tools like ask_pipeworx or discover_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 lists three useful scenarios (discovering hot data sources, confirming canonical tools, aligning use cases). While it does not mention when not to use it, the context is clear enough to guide agent selection. No direct alternatives are named, but the use cases are specific.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint – description adds rich behavioral context: it walks child markets, checks date-axis/threshold ordering, computes partition sum, uses Jaccard similarity filter, drops placeholder slugs, and performs fill check against CLOB depth. No contradictions.

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: first sentence states purpose and default mode, then elaborates each parameter. Could be slightly more concise but every sentence adds value. 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?

Given the tool's complexity (multiple modes, algorithmic details, fill check) and no output schema, the description is remarkably complete. It covers response structure, limitations, edge cases (placeholders, similarity threshold), and cross-references to sibling tool for custom sizing.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description adds substantial meaning beyond schema: explains what each parameter triggers (single-event mode vs cross-event mode), details the subtools within each mode (partition check, fill check).

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

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

Description clearly states "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks". It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach.

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?

Guidance is explicit: call with NO args for trending scan, pass event for specific market, pass topic for cross-event scan. It recommends event mode. However, it lacks explicit when-not-to-use or direct comparisons to siblings, so it's very good but not perfect.

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

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

Beyond annotations, the description discloses caching behavior, response structure including diagnostics, data sources (FRED, GDELT), filter skips, Fed bets exclusion, and details on edge computation. This goes well beyond the read-only and idempotent hints.

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

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

The description is long but front-loaded with the core purpose, followed by structured sections. Every sentence adds value, though some details could be condensed. No fluff.

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

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

Given the complexity (9 parameters, 3 segments, no output schema), the description thoroughly covers return structure, diagnostics, caching, and edge cases. It compensates fully for missing 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?

Each parameter has a detailed description in the schema. The tool description adds extra semantics, e.g., explaining slippage_pp in context of Polymarket fees, why min_kelly doesn't filter partitions, and tradeable-edge knobs. It provides value beyond the schema.

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

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

The description clearly states it scans Polymarket markets for discrepancies with Pipeworx data, and is built for daily betting discovery. It distinguishes from siblings by detailing three segments (model-driven, structural arbitrage, concentrated longshot) and specific models.

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 it's for 'what should I bet on today' and avoids paging through hundreds of markets. It provides clear context but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: data source, trend computation, response structure (tracked with time-series, expired with lifespan, snapshot dates), and notes on interpretation of signed edge_pp_net.

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

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

The description is somewhat long but efficiently organized: starts with core concept, then details response fields and limitations. Every sentence provides value, though could be slightly trimmed.

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 complexity (time-series, multiple response arrays, trend calculation) and no output schema, the description thoroughly explains every aspect of the tool's output and behavior, making it fully understandable.

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

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

Schema coverage is 100%, but the description adds meaning by explaining days as lookback with defaults and window as snapshot family with listed options. It clarifies the purpose of each parameter beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description gives context on when to use (e.g., differentiating fresh vs aged edges) and lists limits like 60-day snapshot TTL and decay from daily closes. It lacks explicit exclusions but the guidance 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description aligns perfectly and adds rich behavioral context: walks the order book ladder, returns fill prices, slippage, verdicts, warns about thin books and forced directional risk. No contradiction; the description supplements the annotations comprehensively.

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 lengthy but information-dense and well-structured: starts with purpose, then required params, then mode-specific details. Every sentence adds value, though it could benefit from bullet points for easier parsing. It is appropriately sized given the tool's complexity.

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

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

Despite no output schema, the description exhaustively lists return fields for both modes, including edge cases (thin_legs, forced_directional_risk). It covers clamp behavior, defaults, and usage constraints, making the tool fully understood without needing to invoke it blindly.

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% but the description adds significant value beyond the schema: explains interpretation of size_usd for both modes, default behaviors, clamping, and side auto-detection for basket mode. This provides the agent with clear, actionable 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 clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and defines two distinct modes (single-market and basket) with specific use cases. It differentiates from siblings like polymarket_arbitrage by explicitly stating when to use it before executing trades.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of misuse (theoretical overround not capturable, partial fills leading to unhedged directional positions), leaving no ambiguity about when to apply the 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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses critical runtime behavior: matching is keyword-based and unverified, Kalshi fees are not modeled so spreads are gross, compatibility codes can coexist with matched pairs, and temporal_alignment null means unknown rather than aligned. It also exposes skipped-counter semantics and flag values, giving the agent a realistic picture of output trustworthiness.

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 is front-loaded with purpose and every block carries distinct safety or behavioral information. It earns a high score because the tool is complex and has no output schema, though it could be tightened by trimming a few repeated warnings like 'in EITHER mode' and 'pre-mapped ≠ tradeable'.

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 and the tool's complexity, the description is remarkably complete: it covers response structure, top_spreads_pp semantics, compatibility codes and flags, temporal alignment fields, fee disclosure, skipped-leg counters, and the limitations of matching. An agent can predict both the behavior and the shape of the returned data without further documentation.

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 already 100%, but the description adds meaning the schema cannot convey: topic is a pre-mapped shortcut list, the explicit ticker/slug parameters override the mapped counterpart, and both modes run the identical token-overlap matcher. It also explains how parameter combinations affect response semantics, which is valuable beyond the 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 opening sentence identifies a specific deliverable: the cross-venue spread between Kalshi and Polymarket for the same resolving question. That verb-plus-resource formulation clearly differentiates it from sibling tools such as polymarket_arbitrage and polymarket_edges, which operate on different venue/edge concepts.

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 thoroughly explains the two modes, when to use topic shortcuts versus explicit custom pairings, and warns that pre-mapped topics often return compatibility warnings and are not automatically tradeable. It does not explicitly name sibling alternatives or state when to prefer them, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and listing behavior, which goes beyond annotations without contradiction.

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

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

Three sentences, each serving a purpose: main action, usage context, and pairing with siblings. No redundant words. Front-loaded with key verb and resource.

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

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

For a simple retrieval tool with one optional parameter, good annotations, and no output schema, the description covers purpose, behavior, scoping, and usage without 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?

Only one parameter 'key' with schema description. Description adds meaning by explaining that omitting key lists all keys, which is consistent with schema and examples.

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

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

Description clearly states the tool retrieves a previously saved value or lists all keys if argument omitted. Verb 'retrieve' and resource 'value previously saved via remember' are specific. Distinguishes from sibling tools remember and forget by mentioning pairing.

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

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

Explicitly says when to use: look up stored context without re-deriving. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable context: it details the data returned (source, citation_uri, raw payload) and the effect of mark_read on future calls. 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 well-structured: purpose first, then return data, filters, mark_read behavior, and polling note. Every sentence adds value without redundancy or verbosity.

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 return structure (source, citation_uri, payload) despite no output schema, and explains all parameters. It is complete enough for a simple polling tool with good 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?

All parameters are documented in schema (100% coverage), so baseline is 3. The description enriches parameters with examples (e.g., 'sec_8k' for type) and explains behavior of mark_read and since, providing meaning beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned data (source, citation_uri, payload). It explicitly distinguishes from sibling tools like list_subscriptions by focusing on alerts, and mentions an alternative access method for scripts/dashboards.

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 suggests polling use and gives an alternative endpoint, implying when to use this tool. However, it does not explicitly compare to sibling tools or state when not to use it, so it lacks clear exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds details on multi-source fan-out, GDELT preference, GNews fallback, and USPTO soft-fail. No contradictions.

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?

Concise yet thorough. Front-loaded with example queries. Every sentence adds value without redundancy.

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

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

Complete for a tool with 3 parameters and no output schema. Covers inputs, sources, fallback behavior, return structure, and alternative 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%, baseline 3. Description adds useful guidance: 'type' only supports 'company', examples for 'since' (ISO/relative), and ticker/CIK formats for 'value'.

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

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

The description clearly states the tool returns a change feed for a company (SEC filings, news, patents) in recent days/weeks/months. It provides example queries and distinguishes from sibling tool 'entity_profile'.

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

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

Explicitly tells when to use (for 'What's new' queries) and when to use 'entity_profile' instead. Also explains fallback behavior (GDELT→GNews) and provides advice on the 'since' parameter.

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 significant behavioral context beyond annotations: scoping by identifier, persistence duration (24 hours for anonymous, permanent for authenticated), and confirms it's a write operation. 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-loading the primary purpose. Every sentence adds value: purpose, usage guidelines, scope details, and companion tools. No unnecessary words.

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

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

For a simple tool with two required parameters and no output schema, the description covers all necessary context: what it does, when to use, scoping, persistence, and companion tools. Complete and self-contained.

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

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

The schema already describes both parameters (100% coverage). The description adds valuable examples for key ('subject_property', 'target_ticker') and value ('findings, addresses'), enriching understanding beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, specifying the resource (key-value pair) and the action (save). It provides concrete examples like 'resolved ticker' and distinguishes from sibling tools by naming recall and forget.

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 when to use the tool ('when you discover something worth carrying forward') and implies it's for persistent storage across sessions. It also recommends pairing with recall/forget, providing clear guidance. Lacks explicit exclusions.

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

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

Even though annotations already mark it read-only and idempotent, the description adds rich behavioral detail: graceful degradation of LEI/FIGI enrichment, cascading internal lookups, explicit `unresolved` reporting, and the `figi_candidates` behavior for ambiguous instrument matches. This goes well 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 long but densely informative and front-loaded with trigger phrases and 'Use FIRST.' Every section adds necessary operational detail, and the structure moves from user intent to supported types to edge cases without 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?

There is no output schema, so the description takes on the burden of explaining return content: source-labelled identifiers, `unresolved` fields, `figi_candidates`, RxCUI citations, and enrichment failure modes. Given the tool's complexity, this is complete enough for an agent to call 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 high, but the description adds significant parameter meaning: value can be a ticker, CIK, ISIN, or name for companies; brand or generic for drugs; with concrete examples. It also gives the crucial caveat to pass only the entity name, not the full noun phrase, for bond lookups.

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

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

The description opens with concrete user query patterns and states the core action: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly differentiates resolve_entity from siblings like entity_profile by positioning it as the ID-resolution step that feeds other 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?

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID,' plus supported entity types and input forms. It does not explicitly name sibling alternatives or state when not to use this tool, 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?

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. No contradictions.

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

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

The description is concise (4 sentences), front-loaded with the main purpose, and every sentence adds value. 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?

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers input parameters and notes the special handling of the first entity. Complete for a comparison tool.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add new parameter semantics beyond what is in the schema. 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 uses a specific verb ('Compare AI visibility across multiple entities side-by-side') and clearly identifies the resource (AI presence). It distinguishes itself from sibling tools like ai_visibility_check by noting it probes multiple entities and ranks them.

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 it is 'useful for competitive AI-marketing audits' and gives an example query. It does not explicitly mention when not to use it or list alternative tools, but the intended use case is clear from the context.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds critical behavioral details: bundlephobia's first measurement can take 5-30 seconds, and partial failures degrade gracefully (sources_failed list). This goes beyond annotations.

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

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

Concise yet comprehensive: 120 words, front-loaded with purpose and usage, then behavioral details and return fields. No wasted sentences.

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

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

Despite no output schema, the description fully explains the return value: summary block fields, per-advisory details, links, and alternative versions. This is contextually complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds value by clarifying that scoped packages (e.g., @types/node) are accepted and version defaults to latest. These are useful for correct invocation.

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

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

Description clearly defines the purpose as a composite check for npm package evaluation using deps.dev and bundlephobia. It distinguishes from sibling tools by specifying the ecosystem and the type of analysis (license, advisories, bundle size, tree-shaking).

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: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also clarifies the limitation to NPM ecosystem, directing users to deps.dev for other ecosystems.

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

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

Annotations already show readOnlyHint, idempotentHint. Description adds: returns passages with offsets and scores, uses BGE embeddings, 500-char windows, 200K char cap with truncation flag. No contradictions.

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?

Well-structured with purpose first, then usage, then technical details. Slightly long but each sentence is informative. 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?

No output schema, but description explains return format (passages with offsets and scores) and technical behavior. All essential context is present.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples for query and reiterates cap for text, adding marginal value beyond 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?

Clearly states the tool does semantic search inside a provided text, with specific examples (SEC 10-K, article). Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and use case for large records.

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

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

Explicitly says to use when the record is too large for the prompt, saving context. Mentions pairing with another tool for grounding. Lacks explicit 'when not to use' but clear context suffices.

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

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

Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical details: auth requirements, subscription types, delivery channel behaviors (SMS cap, webhook signing), and the return of subscription id, all consistent with annotations.

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

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

The description is dense but well-organized, with core purpose first then details. Could be slightly more structured (e.g., bullet points) but every sentence adds value.

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

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

Given no output schema, the description adequately covers purpose, auth, types, delivery, and idempotency. It also positions the tool among many siblings, making its role clear.

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 significantly enriches param understanding with concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topics) and delivery constraints (E.164, verified phone, webhook HMAC), going well beyond the schema's own description.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and it uniquely distinguishes from sibling tools like list_subscriptions and unsubscribe.

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 specifies the requirement of a Pipeworx OAuth account and provides type-specific examples and delivery constraints. It implicitly differentiates from read-only tools but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: it returns categorized examples with exact tool+argument shape, drawn from a live catalog. No contradictions.

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?

Front-loaded with user-facing aliases ('What can I ask Pipeworx?') and concise purpose. Every sentence adds value: usage example, topic parameter, and outcome description.

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, but description fully explains what is returned (category-bucketed examples with tool+argument shape). Covers all lookup and discovery capabilities for a new 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% (the optional topic param is described). Description adds beyond schema: enumerates valid topic values (finance, pharma, etc.) and explains that omitting topic gives a cross-category spread.

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

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

Description uses specific verbs ('returns category-bucketed example questions') and identifies the exact resource ('the onboarding entry point'). It distinguishes from siblings like ask_pipeworx and entity_profile by framing this as the discovery tool.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass the topic parameter. 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?

Description adds significant context beyond annotations: deactivation (not deletion), historical events stay via recent_alerts, and ownership enforcement. Consistent with annotations (destructiveHint=false).

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

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

Three concise sentences, front-loaded with the action, no fluff. Every sentence adds value.

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

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

For a single-param tool with no output schema, description covers purpose, constraint, effect, and link to recent_alerts. Fully adequate.

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

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

Schema description coverage is 100% for the single parameter 'id' (uuid from subscribe). Description adds minimal parameter-specific info beyond purpose context.

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

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

Description clearly states the verb 'Cancel' and resource 'subscription', specifies ownership enforcement and that the row is deactivated not deleted. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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?

Description explicitly says ownership is enforced, guiding the agent to use it only for own subscriptions. Does not mention alternatives for canceling others' subscriptions, but the constraint 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: it explains the fast path vs. grounded pipeline, details the verdict values, describes the failure mode 'could_not_verify' as 'NOT evidence for or against the claim', and clarifies 'unsupported' semantics. It also reveals the efficiency benefit (replaces 4–6 calls). This goes considerably beyond the annotations and is consistent with them.

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

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

The description is long but every sentence earns its place. It opens with concrete query examples to anchor the input format, then briefly explains the dual pipeline, lists return values, and delivers critical caller guidance about error semantics. The structure is logical and front-loaded, and the length is proportional to the tool's complexity. No filler or redundant repetition of schema/annotations.

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 is fully complete for a tool of this complexity. It explains the two routing paths, the verdicts, the citation format, the handling of edge cases (could_not_verify vs. unsupported), and the efficiency gain. Since there is no output schema, the description's explanation of the return structure is essential and sufficient. It leaves no critical behavioral question unanswered.

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?

Even though schema coverage is 100%, the description adds meaningful semantics beyond the schema. For 'claim', it gives natural-language examples and emphasizes the 'natural-language factual claim' format. For 'tolerance_pct', it explains the default behavior ('implied by wording, capped at 5'), how to override it, and provides a specific recommendation (set 1–2 for hallucination detection). This helps the agent select and populate parameters correctly beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources. It provides multiple example phrasings ('fact check', 'verify the claim that…'), explicitly mentions the return verdict types, and distinguishes itself from siblings by noting it replaces 4–6 sequential calls. The verb 'verify' and resource 'claims' are specific, and it differentiates from other tools like ask_pipeworx_grounded by focusing on claim verification rather than general queries.

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

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

The description gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies two distinct routing paths (company-financial claims via SEC EDGAR fast path, all other claims via the grounded pipeline), which tells the agent exactly when this tool is appropriate. It further implies that for non-fact-checking queries, other tools like ask_pipeworx should be used, providing effective context for tool selection.

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