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?

Annotations already communicate read-only, idempotent, non-destructive behavior, so the description only needed to add non-obvious behavior. It does this by revealing that the tool is a dispatcher: it fills arguments for one of 5,596 tools across 1,465 sources and returns structured answers with stable pipewire:// cite URIs. It gives some context but does not discuss failure modes or rate limits.

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

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

The description is longer than strictly needed, but it front-loads the purpose and preference in the first sentence, sets usage triggers, gives examples, then lists alternative tool for edge cases. The structure is logical, easy-to-scan, and every major section remains on-topic, with only minor no-op phrasing at the end.

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 router-like tool with no official output schema, the description covers the key operational facts: the dispatch behavior, the return format, the usage triggers, and the main alternatives. It could add what happens on ambiguity or limits, but it still provides enough context for an agent to invoke it correctly in most cases.

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

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

The schema already documents all six parameters and their aliases with 100% coverage, so the baseline is 3. The description adds useful examples of acceptable natural-language inputs: current US unemployment rate, Apple's latest 10-K, adverse events for ozempic. This reinforces the expected input style at no increase the schema alone already 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 names the exact resource (questions about real-world, structured data) and the verb pair: routes a question to the correct underlying tool and returns a structured answer with citations. It explicitly contrasts itself with web search, so a model can tell what this tool does and why it exists.

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

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

It gives clear trigger phrases and examples, labels the tool as the default START HERE, and explicitly lists when to use alternatives instead: resolve_entity for ambiguity, deep_research for open-ended research, ask_pipeworx_grounded for citation-heavy verification, and recall/memory tools for personal data. This is explicit when-to and when-not-to 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 declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to reiterate safety. It adds value by disclosing that this is the experimental edge and that no candidate is active right now, so behavior matches ask_pipeworx. It also states the fallback behavior is none (it's a full working router). This is good transparent context beyond the annotations, though it doesn't detail which candidates were tested or how results are compared.

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 well-structured, containing a clear contract statement, current state, and usage guidance. Every sentence earns its place – the candidate status detail, the 'use it like ask_pipeworx' instruction, and the fallback clarification all contribute to an agent's decision. It could be trimmed slightly in the middle, but overall it is efficient and focused.

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 beta/experimental tool. It covers current behavior, current state (no active candidates), how to use it, how it compares, and what it is not, the experimental edge. The annotations cover safety, the schema covers parameters at 100%, and output schema is not present but the description states response shape is identical to ask_pipeworx. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description reinforces that parameters are identical to ask_pipeworx and that 'question' is the main input with aliases accepted. It doesn't need to repeat parameter details because coverage is complete and the description clarifies the semantic relationship to the stable sibling.

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

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

The description states a specific verb and resource ('Ask Pipeworx Beta') and immediately distinguishes it from the sibling: identical universal router with candidate routing improvements enabled live. It clearly identifies that no candidate is active now, so it currently matches ask_pipeworx exactly. This is far beyond a vague purpose statement and helps an agent understand what this tool is and how it differs from its siblings.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing; results are compared against the stable router to decide what merges.' This tells the agent when to use this tool versus the stable alternative. It also clarifies that results are experimental and evaluated against ask_pipeworx, giving clear context for choosing this tool.

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

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

The description discloses exactly how the tool behaves beyond annotations: it picks a tool, fills arguments, fetches data, extracts using ONLY tool results, and returns either success with evidence/confidence or a structured refusal with specific reasons. This goes far beyond the safe-read annotations already supplied.

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

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

Despite being dense, every sentence earns its place: mode definition, routing behavior, output contract, return shape, refusal reasons, use cases, and cost/alternative guidance. The most important concept ('hallucination-resistant') is front-loaded.

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

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

Even though there is no output schema, the description fully documents the return shape and refusal semantics. It also covers when to use, when not to use, and key behavioral guarantees, so nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, and the schema already documents the 'question' parameter with aliases. The description does not add parameter-specific detail, but the schema does the heavy lifting, so a baseline score of 3 is appropriate.

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

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

The description states a clear, specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from ask_pipeworx by explaining that it routes the same way but extracts grounded answers and can explicitly refuse when data is insufficient.

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

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

It gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and explicitly says to prefer ask_pipeworx for casual lookups due to the extra LLM call. This is a clear selection rule relative to its sibling tool.

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

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

Annotations already declare readOnlyHint=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?

Far exceeds the readOnly/idempotent annotations: it discloses that outputs are never invented ('explicit gaps[] for facets the data couldn't answer'), that every finding carries a stable, resolvable citation_uri, that large records are semantically excerpted (not head-truncated), and that latency can hit ~90s for 'thorough'. These are behavioral guarantees the annotations do not capture.

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?

Every sentence carries dense, useful signal and the account prerequisite is front-loaded. It loses a point because the whole definition is one long run-on paragraph of em-dashes and semicolons, and the depth explanation partially duplicates the schema description — a short bulleted or a few short paragraphs would be easier and faster to parse.

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

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

Even without an output schema, the description defines the complete output contract: the findings packet shape (verbatim evidence, confidence, source, fetched_at, citations), the gaps[] and contradictions[] fallbacks, and the hop field. It also covers prerequisites, permissions, tiers, latency, and realistic failure modes — enough for an agent to call it and interpret the response without guessing.

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

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

Schema coverage is already 100%, covering the required 'question' and the full 'depth' enum, so the baseline is 3. The description adds meaningful extra semantics: the paid-plan requirement for 'thorough', latency expectations per depth, and the kind of question phrasing ('compare X and Y', 'research the filings plus market picture') that works best.

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

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

The description states a specific verb and resource: 'multi-source research across Pipeworx's 1465 structured data sources', with the concrete mechanism (decompose into facets, route to tools in parallel) spelled out. It explicitly differentiates itself — 'this is NOT open-web search' — and names ask_pipeworx as the single-query sibling alternative, so it cannot be mistaken for any other 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 gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), explicit when-not ('For a single lookup use ask_pipeworx'), and an explicit prerequisite with a redirect ('ACCOUNT REQUIRED... if you are not signed in, use ask_pipeworx instead'). It even notes the paid tier for the 'thorough' depth, leaving no routing decision ambiguous.

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?

Annotations indicate readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false; the description does not contradict these. It adds valuable context about the patent source soft-failing ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated') and the cross-source data flow (SEC, XBRL, USPTO, news, GLEIF), exceeding annotation coverage.

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

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

The description is somewhat long but every sentence serves a purpose—examples, usage guidance, supported parameters, return fields, and caveats. It is front-loaded with example queries. A minor improvement would be to break the return field list into bullet points for faster parsing, but it remains 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 complexity (multiple data sources), 2 required parameters, no output schema, the description thoroughly explains what the tool returns: cik, company_name, recent_filings (with URIs), fundamentals, patents, news, LEI. It covers edge cases (patent soft-fail, name unsupported) and expected output format, making it complete for an agent.

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

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

Schema has 100% description coverage for both parameters. The description adds significant meaning: it clarifies that 'value' can be a ticker or zero-padded CIK, explicitly notes that names are not supported, and provides examples ('AAPL', '0000320193'). This goes well beyond the schema descriptions.

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

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

The description starts with explicit user query examples like 'Tell me about X' and clearly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call.' This immediately conveys the tool's purpose and distinguishes it from siblings like 'compare_entities' which compares entities, or 'resolve_entity' which resolves names to identifiers.

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 'ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view,' giving clear when-to-use guidance. It also advises using 'resolve_entity first if you only have a name' as a when-not-to-use instruction, effectively differentiating from 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 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?

Adds extensive context beyond annotations: two modes, response structure (leg-by-leg prices, spread array), safety fields (compatibility_warning, temporal_alignment, skipped counters). Explains why some pairs are dropped (non-equivalent bet shapes). 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?

Well-structured with headings (TWO MODES, RESPONSE, SAFETY FIELDS). Somewhat verbose but every sentence adds information. Could be slightly tighter without losing 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?

Comprehensive given no output schema: details response format, safety flags, and edge cases (e.g., temporal misalignment, shape mismatches). Covers when spreads are meaningful and when they are not.

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. The tool description adds value by listing the topic shortcuts and explaining override behavior. Examples in schema also help. Slightly redundant but still additive.

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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, distinguishing two modes (topic shorts and explicit tickers). This distinguishes it from sibling tools like polymarket_arbitrage and compare_entities.

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 compare prices across venues for same outcome. Provides when-not-to-use guidance via compatibility_warning, temporal_alignment, and notes that pre-mapped topics often return warnings. Includes alternatives by naming two distinct usage modes.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantial behavioral context: internal cascading through multiple endpoints, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR still returns), identifier labelling with source, and explicit handling of unresolved identifiers. 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 front-loaded with examples and a usage directive, but it is verbose. The 'SUPPORTED TYPES' section contains extensive details that could be shortened or moved to an external reference. While structured, several sentences could be merged without losing meaning. It earns its length for completeness but sacrifices conciseness.

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

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

There is no output schema, so the description must explain return values. It does so thoroughly: for company, it lists all identifiers (CIK, ticker, LEI, FIGI, ownership data) and mentions unresolved identifiers. For drug, it describes RxCUI, ingredient, brand, and citation. It also covers error handling (graceful degradation). Given the tool's complexity and lack of output schema, the description is highly complete.

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

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

Schema coverage is 100% (both parameters documented). The description adds significant meaning: for the 'value' parameter, it clarifies that company accepts ticker, CIK, ISIN, or company name, and explains ISIN-to-LEI mapping. For drug, it specifies brand or generic name. It also adds context about the 'type' parameter's impact on the resolution logic. This enriches the schema beyond the basic enum and string descriptions.

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

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

The description opens with concrete examples of user queries, explicitly states the verb 'resolve a user-spoken NAME to the canonical/official identifiers', and names the specific resources (CIK, ticker, LEI, RxCUI, etc.). It also gives a usage directive: 'Use FIRST whenever you have a name but need an ID.' This clearly distinguishes the tool's purpose from sibling tools (e.g., entity_profile provides further detail, not ID resolution).

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It also implies the tool replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or mention alternatives (e.g., 'if you already have an ID, use entity_profile instead'). The guidance is clear but incomplete.

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.