Climatiq

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

The description adds value beyond annotations by detailing probe behavior, per-model return structure, and cost implications for Anthropic. Annotations already indicate safe read-only operation, and description aligns 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?

Four sentences: first states core purpose and default, second adds optional key detail, third describes return format, fourth lists use cases. No fluff, front-loaded, 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?

Despite no output schema, the description fully covers input parameters (all described), output format (per-model fields + combined view), and usage contexts. Complete for a read-only probe tool with 4 params.

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?

100% schema coverage means schema already defines parameters well. The description adds context: default model, when _apiKey is needed, purpose of 'context' param for disambiguation. This enhances understanding beyond raw schema.

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

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

The description uses specific verb 'probe' and resource 'LLMs', clearly states the output 'score visibility (0-100) per model', and distinguishes from sibling tools like 'ask_pipeworx' which are about answering questions, not measuring visibility.

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 describes when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and mentions model options with cost implications. Does not explicitly list exclusions or alternatives among siblings, but 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses internal behavior: it routes the question to the right tool, fills arguments, and returns a structured answer with stable citation URIs. It also adds contextual expectations by naming the covered data domains and noting that live news is included. It does not discuss latency or failure modes, but the annotations already cover the key safety profile.

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

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

The description is long but every section earns its place: preference directive, domain list, routing behavior, trigger phrases, examples, and sibling alternatives. It front-loads the most important guidance ('PREFER OVER WEB SEARCH') and keeps sibling routing compact. Some trimming of the example list could tighten it, but it is not padded or redundant.

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

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

For a broad question-routing tool with no output schema, the description tells an agent what to submit, how the call is executed, what comes back (structured answer plus citation URIs), and which sibling to choose in edge cases. It also includes real examples that map directly to the listed domains. No critical piece 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?

Schema coverage is 100% and the schema already defines `question` and its aliases clearly. The description adds meaning by illustrating the breadth of accepted natural-language inputs with concrete examples like 'current US unemployment rate', 'Apple's latest 10-K', and 'active clinical trials for GLP-1'. This helps an agent understand what constitutes a valid question better than the schema alone.

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

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

The description opens by positioning this as the go-to factual-data tool ('PREFER OVER WEB SEARCH') and names a concrete mechanism: routing to 5,798 tools across 1,517 verified sources and returning structured answers with pipeworx:// citation URIs. It also differentiates from siblings by explicitly naming ask_pipeworx_grounded, ask_pipeworx_beta, and deep_research as distinct alternatives. The verb-resource relationship is clear: ask a natural-language factual question and get a cited structured answer.

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 trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current') and says to use this tool even when web search could also answer. It also provides explicit when-not-to-use guidance by directing grounded fact-checks to ask_pipeworx_grounded, fast multi-hop queries to ask_pipeworx_beta, and comprehensive big multi-part questions to deep_research. This is strong, actionable routing 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond those hints: this is an experimental beta with candidate routing improvements that may be live, none are active right now, and it is a full working router rather than a fallback or stub. This is exactly the kind of behavioral disclosure an agent needs.

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: beta identity and scope, current candidate status, usage directive, and a clarifying note that this is a fully functional router. It is front-loaded with the most important distinction and avoids 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 tool with one required parameter, full schema coverage, and safety annotations, the description is complete. It explains the tool's experimental nature, current parity with ask_pipeworx, how to use it, and that the response shape matches ask_pipeworx. The agent has enough context to select and invoke it correctly.

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

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

The input schema already documents all six parameters with 100% coverage, including the 'question' parameter and its aliases. The description does not add parameter-level details beyond saying it accepts the same arguments as ask_pipeworx, which is reasonable but not additional semantics. Baseline 3 is appropriate given full 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 identifies this as the beta version of ask_pipeworx, a universal router with the same 5,798 tools, arguments, and response shape. It differentiates itself from the stable ask_pipeworx by emphasizing the experimental routing edge, and explicitly names ask_pipeworx as the reference point.

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 it exactly like ask_pipeworx when you want the newest routing, and notes that results are compared against the stable router. It explains the current state (no active candidate, so it matches ask_pipeworx exactly), but it does not explicitly state when not to use it or directly compare against other siblings like ask_pipeworx_grounded.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behaviors: answers are extracted only from tool result content, refusals are explicit, and the tool costs an extra LLM call. It also enumerates the exact refusal reasons, giving an agent a detailed behavioral contract.

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

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

The description is dense but every sentence earns its place: it states the mode, the routing, the return contract, refusal behavior, usage context, and cost tradeoff. The critical distinction from ask_pipeworx is front-loaded, and the guidance is direct.

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?

Although there is no output schema, the description provides the success shape, refusal shape, refusal_reason enum, usage criteria, and cost tradeoff. Combined with full parameter schema coverage and clear annotations, an agent has everything needed to call this 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 description does not add parameter-level detail beyond the schema, but the schema already covers 100% of parameters with aliases and a clear natural-language question field. Since schema coverage is complete, the baseline of 3 is appropriate.

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

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

The description names a specific mode ('Hallucination-resistant answer mode for high-stakes reads') and ties it to a concrete resource (Pipeworx, selecting among tools and sources). It clearly differentiates from ask_pipeworx by emphasizing extraction-only answers and explicit refusals, so an agent can distinguish it from siblings without opening 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?

The description explicitly states when to use this tool: when an answer will be quoted, cited, or acted on and the agent must not invent facts. It also gives the alternative preference: 'prefer ask_pipeworx for casual lookups,' with a cost-based reason. This is direct, actionable guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, establishing safety and idempotency. The description goes far beyond by detailing behaviors such as short-circuiting on low-confidence matches, handling closed/dead markets, wide-spread market warnings, resolution-rule risk (cancellation_rule), and parent_event extraction. This provides comprehensive behavioral transparency.

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

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

The description is thorough but lengthy, with extensive details about classifiers, fan-out examples, edge cases, and result structures. While every sentence adds value, it could be more concise by front-loading the main purpose and usage, and moving detailed behavior explanations to supplementary sections. It is not tightly structured for quick scanning.

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

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

Given the absence of an output schema, the description thoroughly explains return shapes (result.market, result.analysis, result.evidence), resolver contracts (market_match_confidence, alternatives, suggestions), parent_event fields, news fields (fallback attempts), safety behaviors (low-confidence short-circuit, closed markets), and resolution-rule risk. It covers all relevant edge cases and outputs, making it highly complete for an agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100% with descriptions for all three parameters (market, depth, include_raw). The description adds significant context beyond the schema, e.g., how to format the market parameter (slug, URL, or question text), the difference between 'quick' and 'thorough' depth, and the effect of include_raw on response size. Examples in the input schema further aid understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with a specific verb ('Research') and resource ('Polymarket bet'). It specifies inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). While not explicitly differentiating from siblings like polymarket_edges or polymarket_arbitrage, the description provides enough context to indicate it is the comprehensive research 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 explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides clear use cases but does not explicitly list when not to use it or name alternative tools for specific scenarios. However, the detailed fan-out examples and classifiers implicitly guide appropriate usage.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds data sources (SEC EDGAR for companies, FAERS for drugs), sorting behavior, and citation URIs—valuable context 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 dense paragraph front-loaded with trigger phrases. Efficient but could benefit from bullet points or clearer separation of details.

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

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

No output schema, but description mentions 'paired data + citation URIs'. For a tool with two distinct entity types and multiple entities, the description covers purpose, usage, parameters, and behavior adequately.

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 explains meaning of type parameter (company vs drug), formatting of values (tickers/names, 2-5 items), and data pulled for each type—adds significant 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?

Describes specific verbs ('compare', 'vs', 'versus', 'rank', 'head to head'), names the resource (companies/drugs), and distinguishes from sequential lookups.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides clear when-to-use examples. No misuse conditions needed beyond that.

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?

Adds substantial context beyond the annotations: auth/tier requirements, latency expectations (15-60s, up to ~90s for thorough), the never-invented guarantee with explicit gaps[], the fetchability guarantee for citation_uri, semantic excerpting behavior, and the hop-based depth semantics. No contradiction with readOnly/openWorld/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?

Long but earned: the auth gate and sibling redirect are front-loaded, then core behavior, then per-depth nuances, then timing. Minor redundancy exists — the depth-level behavior is partially restated from the schema, and the parenthetical example questions slightly duplicate the 'best for' statement.

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 highly complex tool with no output schema, the description fully carries the burden of explaining the return value: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], and hop fields. Auth, timing, citation semantics, and excerpting are all covered; nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real value: it maps each depth level to behavioral outcomes (single hop vs. gap-recovery vs. iterative lead-chasing), adds latency implications, and clarifies the paid requirement for thorough. The question parameter gains meaning through the decomposition explanation and concrete example phrasings.

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?

States a specific verb and resource: grounded multi-source research across Pipeworx's 1517 structured data sources in one call, explicitly distinguishing itself from open-web search. The sibling ask_pipeworx is named as the single-lookup alternative, so an agent can differentiate them without opening either 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?

Gives explicit when-to-use ('best for broad/multi-part questions over structured data'), when-not-to-use ('for a single lookup use ask_pipeworx'), and an auth-based redirect ('if you are not signed in, use ask_pipeworx instead'). This is textbook routing guidance with named alternatives.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds useful behavioral details: returns top-N results with full schemas and examples, ready to call without a second lookup. 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 front-loaded with purpose and examples, then adds usage guidance. It is slightly long but every sentence adds value. Could be more concise, but very clear.

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 high schema coverage, annotations, and the description's detailed return format explanation (top-N tools with full schemas and examples), the description is fully complete for an AI agent to understand and invoke the tool.

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

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

Schema coverage is 100%, but the description adds meaningful context: natural language description examples and lists all parameter aliases (task, q, description, search). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: find tools by describing data or task. It lists numerous specific use cases (SEC filings, financials, etc.), distinguishing it from sibling tools like 'deep_research' or 'search_factors' that have narrower scopes.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear context for when to use. Does not explicitly name alternatives, but the guidance is strong enough.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses meaningful runtime behavior: it fans out across many sources in parallel, soft-fails for sunset APIs, uses GDELT→GNews fallback, returns resolved:false for private companies, and explains that empty sections are real 'no data' rather than failures. It also notes that missing FDA-licensed biologics is expected for small-molecule/generic companies. This is strong behavioral disclosure that goes well beyond the structured hints.

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

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

The description is long, but every sentence earns its place: examples are front-loaded, the source list and return fields are compactly organized, and caveats are attached to the relevant sections. For a tool with no output schema, this density is justified and well structured rather than verbose.

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

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

Given the lack of an output schema and the high complexity of a multi-source entity profile, the description is remarkably complete: it lists all upstream sources, each returned field with caveats, the input formats, failure semantics, and how to interpret empty sections. An agent has enough context to invoke the tool correctly and interpret its results without additional 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 100%, so the baseline is 3, but the description adds practical semantics: both type values are interchangeable, value can be a ticker, zero-padded CIK, or company name, and names resolve via SEC EDGAR. It also clarifies the resolved-from/resolved-to behavior and the private-company resolution failure mode, which are valuable beyond the raw schema.

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

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

The description opens with concrete user phrasings and names the resource precisely: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates itself from sibling tools like compare_entities and deep_research by defining entity_profile as the single-call holistic company lookup, and from resolve_entity via the profiling behavior. A specific verb, resource, and scope are all present.

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 includes an explicit routing directive: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also details input forms, the private-company behavior, and the type/value interchangeability, so an agent knows when to invoke this tool and what to expect. It names the alternative approach (chaining lookups) and the conditions that select this tool instead.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it returns CO₂e plus a breakdown, which is transparent about the output. 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?

Two concise sentences: first states the purpose, second explains the required inputs and output. Every word 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?

The description is complete for a calculation tool with output schema. It mentions return value ('CO₂e + breakdown'), references the prerequisite sibling tool (search_factors), and provides adequate guidance.

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 valuable context with an example (energy:200, energy_unit:'kWh') and clarifies the minimum requirements for emission_factor (activity_id or id), which goes 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 verb 'Calculate kgCO₂e' for an 'activity', specifying the exact metric and distinguishing it from sibling tools like search_factors which find factors rather than compute emissions.

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 requires an emission_factor from search_factors and parameters, providing an example. However, it does not explicitly state when not to use this tool or suggest alternatives beyond the implicit prerequisite.

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 destructiveHint=true and readOnlyHint=false. Description adds context about use cases (clearing sensitive data, stale context) but does not mention permanence or side effects. 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?

Two sentences, front-loaded with verb and resource. No unnecessary words; 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 one-parameter delete tool with clear annotations, the description fully covers purpose, usage, and pairing. No output schema needed.

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 parameter 'key' described as 'Memory key to delete'. Description adds no additional parameter information beyond what the schema provides.

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 'Delete a previously stored memory by key', providing a specific verb and resource. It distinguishes from sibling tools by mentioning pairing with remember and recall.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with remember and recall, guiding agent on alternatives.

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

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

The description adds behavioral context beyond the annotations: it explains the process (fetches page, extracts title/description/key links) and output format (standard llms.txt markdown). Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and the description aligns with these. 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 two concise sentences plus a use-case list. It is front-loaded with the core action and benefit, then details. No redundant phrasing, but could be slightly more compact by integrating the list into a single sentence.

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 rich annotations and 100% schema coverage, the description completes the picture by specifying output format and placement. It lacks error handling details or rate limits, but for a simple read-only tool this is acceptable and usable.

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 parameters. The description does not add extra detail on parameter semantics (e.g., URL format, default max_links). It focuses on overall tool behavior, so it meets the baseline but does not exceed.

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 verb 'Generate' and the resource 'llms.txt file for any URL'. It specifies the output format and purpose for AI crawlers, and distinguishes from related sibling tools like scan_competitor_ai_presence by listing specific use cases: getting a client's site indexed, drafting for own project, or auditing competitors.

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 provides usage scenarios with 'Useful for:' followed by three clear examples. It gives context on when to use this tool, though it does not explicitly state when not to use or point to alternatives. The clarity is sufficient for most agents.

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. The description adds value by listing the specific return fields (id, type, params, etc.) and mentioning the optional parameter, providing context 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?

Two concise sentences that efficiently convey purpose, return structure, and usage context without 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 list tool with one optional parameter, the description sufficiently covers return fields and usage guidance. No output schema needed since return fields are described.

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 (include_inactive), and the schema description already fully documents it. The tool description does not add additional meaning, so baseline 3 applies due to 100% schema coverage.

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

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

The description uses a specific verb ('List') and resource ('the caller's active subscriptions'), and lists returned fields (id, type, params, etc.), clearly distinguishing 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?

Explicitly states when to use ('review what you're monitoring before adding more or to find an id to cancel'), providing clear context. Lacks explicit when-not-to-use or alternatives, but is helpful.

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

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

Annotations declare readonlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering safety and idempotency. The description complements this by specifying the output contains unit-type families and their units, adding behavioral context 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 sentence that is front-loaded with the verb 'list' and the resource. No wasted words; every part contributes to clarity.

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 zero parameters, rich annotations, and an output schema (as indicated by context), the description is complete. It tells the agent exactly what the tool returns, which is sufficient for a simple list operation.

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?

Tool has zero parameters, so baseline is 4. The description correctly implies no input needed, and schema coverage is 100%, so no additional param info is required.

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 lists unit-type families (e.g., Energy, Volume) and their valid units. Verb 'list' with specific resource 'supported unit-type families and their valid units' distinguishes it from all sibling tools, none of which offer similar functionality.

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

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

The description implies usage when an agent needs to know supported unit types and units. No explicit when-not-to-use or alternatives are mentioned, but the tool is self-contained and simple; no other sibling tool offers this capability, so guidance is adequate albeit implicit.

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

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

Annotations are all false and provide no safety profile, so the description carries the full burden. It discloses the claim_token workflow ('Filing without an account returns a claim_token...pass it back later'), rate limiting ('5 per identifier per day'), cost ('Free'), and operational details (team reads digests daily). No contradiction with annotations; this is exemplary behavioral transparency.

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

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

The description is a single dense paragraph that front-loads the core purpose and use cases, then layers constraints and follow-up mechanics. Every sentence adds necessary guidance for a tool with nuanced usage (claim_token, rate limits, cross-server scoping). No filler or repetition; the length is justified by the tool's complexity.

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

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

This feedback tool has nested context, an enum, and no output schema, yet the description covers all critical aspects: when to use, exclusions, how to structure input, what the claim_token return is, rate limits, and quota impact. Given the schema+annotations richness is low (no output schema, all-false hints), the description fully compensates and leaves no major gap for an agent to misuse the tool.

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

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

Schema coverage is 100%, giving baseline 3, but the description adds significant meaning beyond field names. It explains the claim_token lifecycle in detail—how to obtain it and reuse it to read status—which the schema only describes as 'Read the reply to a report you filed earlier.' It also binds message content guidance ('Describe the issue in terms of Pipeworx tools/packs') to the context object, enriching the semantics of multiple parameters.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact scenarios (bug, feature/data_gap, praise), making the purpose unmistakable. It also clearly distinguishes from siblings like ask_pipeworx by positioning this as feedback/reporting rather than question-answering.

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

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

Explicit when-to-use guidance covers three cases (wrong/stale data, missing tool, something worked well) and explicit when-not-to-use: 'ONLY for tools served by this Pipeworx connection' with the alternative 'file it with that server instead.' It also instructs on phrasing (describe in terms of Pipeworx tools/packs, don't paste end-user prompt) and how to check resolution status via claim_token, going well beyond a simple trigger.

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, not destructive. The description adds valuable context: data derived from CF analytics-engine, no PII, caching behavior (5min-1h), and self-aggregating nature.

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 concisely structured with bullet points for use cases and no fluff. Every sentence adds value, and it is front-loaded with the core purpose.

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

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

Given the tool is simple (one optional parameter, read-only), the description is very complete: it explains output components, data source, caching, and use cases. Lacks explicit output format, but that is not critical here.

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

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

Schema coverage is 100% with a well-described enum. The description adds meaningful nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances the parameter 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 returns top tools, top packs, and total call volume over a selected window. It specifies the verb 'returns' and the resource 'trending data on Pipeworx', distinguishing it from siblings 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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, aligning use case). It provides clear context for when to use but does not explicitly exclude scenarios or name alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context including semantic anchor, partition filter, and fill check, warning about not trading when realizable_edge_pp ≤ 0. 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 quite lengthy with several sentences covering detailed behavior. It is front-loaded with a clear purpose statement, but could be more concise by removing redundant explanations of internal mechanics.

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

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

Despite lacking an output schema, the description thoroughly explains return values (opportunities[], partition_check, fill check) and provides enough context for an agent to understand usage and tradeoffs, making it complete for a complex arbitrage 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?

Both parameters have descriptions in the schema, and the description expands with examples of valid values (e.g., 'fed-decision-may-2026') and explains the behavioral differences between modes, adding significant 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 states the tool's purpose as finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes from sibling tools like polymarket_edges or polymarket_fill_risk by specifying its unique functionality.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, 'event' for a specific market, 'topic' for cross-event scanning. It recommends 'event' for specific markets but does not explicitly state when not to use the tool or mention alternatives.

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

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

The description goes far beyond the annotations (readOnly, idempotent, etc.), detailing caching behavior, response structure with diagnostics, model families, edge calculations, slippage, and tradeable-edge filters. It explains why segments may be empty and how to interpret results, providing complete behavioral context.

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

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

The description is long but well-structured with clear sections (model families, response, knobs). Every sentence adds value, though some details could be streamlined. The front-loaded purpose and segment explanations make it navigable.

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, no output schema), the description is thorough, covering response structure, diagnostics, caching, and edge cases. It compensates for missing output schema by detailing returned fields and provides enough context for an agent to use the tool effectively.

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

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

Although schema coverage is 100%, the description adds rich context to each parameter, explaining defaults, tradeable-edge filters (e.g., min_liquidity, max_spread_pp), and how parameters like min_kelly and min_partition_leg_kelly interact. This significantly enhances 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's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and targets the use case 'what should I bet on today'. It distinguishes from siblings by focusing on edge discovery across multiple model families, not just arbitrage or tracking.

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

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

The description explicitly says it's for discovering betting opportunities without paging many markets. It provides knobs for filtering but does not explicitly list when not to use or compare with sibling tools like polymarket_arbitrage. However, the purpose is clear enough to guide 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?

The description extensively covers behavior beyond annotations: history depth bounded by 60-day TTL, snapshot creation triggers, decay computed from daily closes, and response structure. No contradictions with readOnlyHint, openWorldHint, idempotentHint, 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?

The description is a single dense paragraph well-structured with purpose, args, response, and limitations. Every sentence adds value, though slightly verbose.

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

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

Without an output schema, the description fully specifies the response format and field meanings. It also covers limitations, parameter defaults, and dependencies. 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%, and the description restates defaults and clamps already present in schema. It adds minimal new meaning beyond the schema's parameter 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 tracks edge persistence and decay over time, answering specific temporal questions about edges. It distinguishes itself from siblings like polymarket_edges by focusing on historical telemetry rather than current snapshots.

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

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

The description provides context for when to use (e.g., to distinguish fresh vs. old edges) but does not explicitly state when not to use or mention alternative tools. The 'Answers...' framing implies usage intent.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral traits: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains forced_directional_risk. No contradiction with annotations.

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

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

The description is long but well-structured: a core summary followed by detailed mode explanations and usage guidance. It front-loads the key purpose and uses clear section headings. While verbose, every sentence adds value 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?

With no output schema, the description fully covers return values, listing fields for both modes. It also explains edge cases (thin_legs, forced_directional_risk), parameter requirements, and the rationale behind usage thresholds. All necessary context is provided.

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 a baseline of 3 is appropriate. The description adds further meaning by explaining size_usd semantics for buys vs sells, the auto-detection of side for basket, and the distinction between market and event. This deepens understanding beyond schema descriptions.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes two modes (single-market and basket) and uses specific verbs like 'check' and 'returns'. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly advises to use this tool 'before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about thin books and partial basket fills converting an arb into an unhedged directional position, providing 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral transparency: it discloses that compatibility_warning and compatibility_codes[] can be non-empty even with matched_pairs>0, describes all six compatibility codes and their meanings, explains that legs with 'unknown' metric_type or match_subtype are never paired, clarifies that temporal_alignment:null means 'not computed' rather than aligned, and discloses that spreads are gross (not net) because Kalshi fees are not modeled. This goes well beyond the annotations and provides critical caveats for safe use.

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, but it is well-structured: it front-loads the core purpose and modes, then lays out response fields, safety codes, and caveats in a logical order. Every sentence adds informational value for a complex tool with many edge cases and safety flags. It could be tightened (e.g., merging some repeated mentions of modes and 'read them even when matched_pairs>0'), but it's not bloated; it earns its length 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?

With no output schema provided, the description carries the full burden of explaining return values. It covers the response structure (leg-by-leg prices, top_spreads_pp, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, skipped counters), explains the meaning of nil/unknown values, and details all safety fields and codes. It also notes real-world expectations (rare tradeable spreads, pre-mapped ≠ tradeable). Nothing essential for an agent to call this correctly and interpret results is missing.

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

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

Schema coverage is 100% (all three params have descriptions), but the description adds significant meaning: it explains the topic parameter's pre-mapped shortcuts and auto-fetch behavior, clarifies that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and details how the two modes interact. It also provides examples in the schema and describes the dual-mode behavior in prose. The description enriches the schema without redundancy.

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 an explicit, specific purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes on to enumerate two operational modes (topic shortcuts vs explicit ticker/slug) and clarifies what the tool computes (leg-by-leg prices, matched spread, top_spreads_pp). This clearly differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges by naming the two venues and the specific analytical output.

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

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

The description gives clear guidance on when to use each mode: topic mode for pre-mapped shortcuts, explicit mode for custom pairings. It also warns that most pre-mapped topics return compatibility_warning today, tempering expectations. However, it does not explicitly contrast with alternative sibling tools (e.g., when to use polymarket_arbitrage instead), so it lacks explicit exclusions or comparisons. The context for this tool's own usage is thorough.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms non-destructive behavior and adds detail on scoping (anonymous IP, BYO key hash, account ID). 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?

Two sentences, front-loaded with the core action, no redundancy. Each sentence adds meaningful guidance without waste.

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, description explains the full behavior (retrieve specific, list all, scoping, pairing with siblings). All essential information for an agent 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 description for 'key'. Description adds functional nuance: 'omit to list all keys' and context about usage, adding 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?

The description uses specific verbs ('retrieve', 'list') and clearly identifies the resource ('value previously saved via remember'). It distinguishes from sibling tools like remember and forget by mentioning its complementary role.

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 ('to look up context stored earlier') and what to avoid ('without re-deriving it from scratch'). Mentions scoping and pairing with remember/forget, though does not explicitly exclude alternative tools.

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

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

Adds behavioral details beyond annotations: describes return fields (source, citation_uri, raw event payload), mark_read side effect (next call shows newer events), and polling compatibility. 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?

Single paragraph, front-loaded with main purpose. Every sentence adds value. Could be more structured (e.g., bullet points) but remains efficient and readable.

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?

Covers essential aspects for a read-only tool with 5 optional parameters: explains return structure, mark_read functionality, polling, and an alternative access method. No output schema needed as description explains return fields.

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. Description adds value by providing examples (e.g., 'sec_8k' for type) and clarifying mark_read's effect on subsequent calls. This extra context justifies a higher score.

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

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

Clearly states the verb 'pull' and resource 'fired events from subscription feed'. Description distinguishes it from sibling tools like 'list_subscriptions' by focusing on recent alerts with specific fields, but no explicit sibling differentiation.

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

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

Provides clear usage context: filtering by type and since, mark_read behavior, and mentions polling suitability and an alternative endpoint. However, it does not explicitly state when not to use or compare to similar sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavior: parallel calls, source fallback logic, soft-fail for patents, and return structure. 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 but efficiently packs information. It front-loads example queries and usage patterns. Could benefit from bullet points for clarity, but no unnecessary 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 no output schema, the description details the return structure (changes[] grouped by source, total_changes count, citation URIs). It also mentions tool context and alternative tool (entity_profile), making it complete for an 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% and all parameters have descriptions. The description adds further value by explaining the `since` format (ISO or relative), recommending '30d' or '1m', and clarifying the `value` can be ticker or CIK.

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

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

The description explicitly states the tool provides a change feed for a company, aggregating from SEC EDGAR, GDELT/GNews, and USPTO. It uses specific verbs ('fans out') and distinguishes from sibling tool 'entity_profile', which provides a static profile.

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

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

The description gives explicit example queries ('What's new with X', 'latest on Y') and directly states when to use this tool vs. entity_profile. It also explains fallback behavior and parameter semantics clearly.

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

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

Annotations provide idempotentHint=true, destructiveHint=false. Description adds valuable context about scoping, persistence (24-hour vs persistent), and being readonly-safe. 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?

Single paragraph, well-structured with clear purpose first. Covers key points without redundancy. Could be slightly more concise but 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 the simple tool (2 string params, no output schema), the description fully explains behavior, use cases, and pairing with related tools. 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 provides full descriptions for both key and value parameters (100% coverage). Description does not add new semantic detail beyond the existing 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?

Description clearly states the tool saves data for reuse across conversations/sessions, with specific verb 'Save' and resource 'data'. It also distinguishes from sibling tools '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?

Explicitly says when to use: 'when you discover something worth carrying forward' and provides examples. Mentions pairing with recall and forget for retrieval/deletion.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes well beyond those by disclosing internal cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, the return of figi_candidates on ambiguous matches, and explicit unresolved fields. These are meaningful behavioral disclosures that the agent could not infer from annotations alone.

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 most sentences earn their place given the tool's complexity and the absence of an output schema. It is front-loaded with recognizable user queries and the core directive. Some parenthetical asides could be tightened, but the structure is well organized around supported types and edge cases.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: it lists returned identifiers (CIK, LEI, FIGI, RxCUI), labels sources, handles unresolved identifiers, describes ambiguous matches via figi_candidates, and explains degradation behavior. For a two-parameter tool with this complexity, nothing critical is missing.

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

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

Schema coverage is 100%, but the description adds substantial parameter guidance. It explains accepted input formats for 'value' (ticker, CIK, ISIN, brand/generic name), gives examples like 'AAPL' and '0000320193', and warns against passing full noun phrases that include security-class words. It also clarifies what the 'type' enum implies about resolution behavior. This far exceeds the baseline for high schema coverage.

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

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

The description clearly states a specific verb and resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives many concrete query examples and enumerates supported types, making its purpose unmistakable. It also distinguishes its role from sibling tools by positioning it as the first step whenever a name needs an ID.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' and gives type-specific usage contexts for company and drug lookups. It does not explicitly name alternatives or state when not to use this tool versus sibling tools like entity_profile or compare_entities, but the usage guidance is otherwise clear and actionable.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds behavioral details: probes each entity, calls ai_visibility_check, returns ranked list with score/confidence/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?

Two sentences with no fluff. First sentence defines core action, second adds use case and output details. Perfectly front-loaded and efficient.

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

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

For a comparison tool with rich annotations and full schema coverage, description covers all necessary aspects: purpose, inputs, behavior, output. No missing information.

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

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

Schema coverage is 100% with good descriptions. Description adds practical context: first entity is 'subject', others competitors; explains models default and apiKey requirement. Enhances understanding 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?

Description specifies verb 'compare', resource 'AI visibility', and the exact action: probes entities, ranks by score, surfaces recognition. Clearly distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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?

States 'useful for competitive AI-marketing audits' with an example question, providing clear context. Does not explicitly mention when not to use or list alternatives, but the purpose is well-defined enough.

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

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

Beyond readOnlyHint and idempotentHint annotations, description reveals composite behavior (fans out to two services), latency for first bundlephobia measurement (5-30s), and graceful degradation with sources_failed. 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?

Efficient single paragraph with front-loaded purpose. Every sentence adds value, covering usage, behavior, and return data without redundancy.

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

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

Despite no output schema, description comprehensively lists return fields (summary block, advisories, links, alternatives) and covers all relevant aspects of tool usage and behavior.

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

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

Schema already covers both parameters with descriptions. Description adds context that package accepts scoped names and version defaults to latest, which is helpful but not required given 100% schema coverage.

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

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

Description clearly states the tool performs a composite check for npm package evaluation using deps.dev and bundlephobia. It explains what it checks (license, advisories, bundle size, etc.) and distinguishes it from sibling tools that are unrelated or focused on other ecosystems.

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: 'whenever an agent asks "is X safe / popular / small"'. Also specifies NPM-only scope in v1 and alternatives for other package managers via deps.dev:version. Addresses partial failures gracefully.

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

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

Annotations provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds workflow context (discovery before estimation) and filtering dimensions, which complements the 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?

Two sentences covering purpose, usage, and filters with no unnecessary words. Front-loaded and efficient.

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

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

Given the output schema exists, parameter coverage is high, and annotations are present, the description adequately explains the tool's role and available filters.

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

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

Schema description coverage is 100%, so baseline is 3. The description lists filters and provides examples (e.g., 'EPA', 'DEFRA', ISO code), adding slight nuance but not significantly 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 searches Climatiq's emission-factor database to discover factor IDs and required parameters before calling estimate_emissions, distinguishing it from sibling tools like estimate_emissions.

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 says 'Use to discover factor IDs and required parameters before calling estimate_emissions', implying when to use it. It does not explicitly mention when not to use it or alternatives, but the sibling tool list clarifies 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral detail: embedding model (BGE-base-en), similarity method (cosine), windowing (500-char overlapping), character limit (200K chars with truncation and flagging). 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 concise and front-loaded, immediately stating the tool's purpose. Every sentence adds value: use case, how it works, pairing suggestion, technical details. No wasted words. Each sentence earns its place.

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

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

Given no output schema, the description covers the return value (top-N passages with character offsets and similarity scores), the embedding approach, windowing strategy, character limit, and truncation behavior. It fully explains the tool's behavior for an AI agent to use 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%, providing baselines for each parameter. The description adds extra context: explains the 'text' parameter's max size (~200K), the 'limit' default (5) and range (1-20), and gives example queries. However, it does not fully describe the return format beyond mentioning offsets and scores.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific language like 'semantic search INSIDE a fetched record' and gives concrete examples (SEC 10-K, article). It distinguishes itself from sibling tools by explicitly mentioning pairing with 'ask_pipeworx_grounded'.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also suggests pairing with a specific sibling tool and explains the benefit of offset for verifying quotes.

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: OAuth requirement, rate limits (10/day cap), phone verification, and delivery channel behavior. It does not explicitly address idempotency (though annotated idempotentHint=true), but overall transparency is high.

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 main purpose and prerequisites, followed by types and delivery details. It is dense but not overly verbose; minor improvement could be bullet points for readability.

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 effectively covers return value, all parameter semantics, delivery options, and constraints. It reasonably prepares an agent to invoke the tool correctly.

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

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

With 100% schema coverage, the description enriches parameter meaning with concrete examples, type-specific filters, and delivery channel semantics (e.g., webhook HMAC signing, auto-disable). This goes well beyond what the schema provides.

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 creates a proactive monitoring subscription and returns an ID. It distinguishes the tool from siblings (like list_subscriptions, unsubscribe) by implicating creation, but does not explicitly compare to 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 specifies prerequisites (Pipeworx OAuth account) and provides usage context for different subscription types. However, it does not explicitly state when not to use this tool or mention alternatives among 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=true, idempotentHint=true, and destructiveHint=false, which cover safety and idempotency. The description adds valuable behavioral context: it returns example questions with exact tool+argument shapes, and can produce a broad or focused spread. This goes beyond annotations without contradicting them.

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

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

The description is information-dense but efficient: it starts with common user queries, states the purpose, describes the return format, and ends with usage guidance. Every sentence adds value, though the bullet list of categories could be slightly streamlined. Still, it's well-structured and front-loaded.

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

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

For a tool with one optional parameter and no output schema, the description is remarkably complete. It explains the return structure (category-bucketed with tool+argument shapes), the use case (onboarding), the scope (live catalog of thousands of tools), and how to customize via topic. Sibling tool references provide additional context for selection.

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 describes the topic parameter with allowed values. The description adds meaning by explaining the effect of omitting the parameter (full spread) and the purpose of providing it (focus), as well as listing example topic values. This adds contextual value beyond the schema's technical specification.

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

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

The description explicitly states 'the onboarding entry point for an agent that just connected and wants to know what is worth asking' and describes the tool's action: returning category-bucketed example questions. It distinguishes from siblings by positioning it as the first tool to use, clearly differentiating from meta-tools like ask_pipeworx.

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

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

The description gives explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains how to adjust behavior (with or without topic) and contrasts with other tools by referencing them as 'meta-tools' to learn from.

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: it states ownership enforcement, that the row is deactivated (not deleted), and that historical events remain accessible via 'recent_alerts'. This aligns with annotations (destructiveHint=false) and adds value.

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

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

The description is two clear sentences with no wasted words. The first sentence states the core action, and the second adds essential behavioral detail. It is front-loaded and efficient.

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

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

Given the simplicity (1 parameter, no output schema), the description provides sufficient context: the deactivation behavior and link to 'recent_alerts'. It could mention return value or error cases, but overall it is adequate for a straightforward cancellation 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%, and the parameter 'id' is well-described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond what the schema provides, so 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 ('Cancel a subscription by id') and resource (subscriptions), and the title specifies 'Unsubscribe from Alerts'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by the cancel action and ownership enforcement.

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 is implied by the tool name 'unsubscribe' and title, but there is no explicit guidance on when to use this tool versus alternatives like 'list_subscriptions' or 'subscribe'. The description lacks when-to-use or when-not-to-use statements.

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 read-only/open-world/idempotent, and the description adds substantial beyond-annotation behavior: the verdict taxonomy, the crucial distinction between could_not_verify (check did not happen) and unsupported (no source found), and the tolerance override semantics. This fully discloses behavior a caller must know.

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?

Though moderately long, every sentence earns its place: usage triggers, routing logic, verdict values, and two critical error-semantics clarifications. It is front-loaded with natural-language examples and avoids 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?

Despite no output schema, the description covers what the tool returns (verdict, actual value, citation, reasoning) and explains edge cases (could_not_verify vs. unsupported). Given the tool's complexity and the 100% schema coverage, this is a complete and self-sufficient 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 covers 100% of parameters, and the description enriches both: claim gets realistic examples, tolerance_pct gets why/when to override (hallucination detection) and default behavior (implied by wording, capped at 5). This goes beyond schema descriptions by adding intent and boundary conditions.

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 natural-language triggers ('Is it true that…', 'fact check') and a specific verb+object: verify factual claims against sources. It differentiates this from the sibling Q&A tools (ask_pipeworx_grounded) by framing it as a verification tool with a verdict, not an open-ended answer 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 when to use ('Use whenever... factually correct') and describes routing for company-financial vs. all other claims. It does not name sibling alternatives or state when not to use it, but the trigger conditions and the 'Replaces 4–6 sequential calls' note give clear practical guidance.

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