Tradier

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the default free model (Workers AI Llama-3.3-70b), the BYO key model for Anthropic, and the return structure (per-model scores and combined view). 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 three sentences long, with the core action and purpose front-loaded. Every sentence conveys necessary information without redundancy, achieving maximal efficiency.

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

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

Despite no output schema, the description explains the return format (per-model score, confidence, signals, raw_response, and combined view). All 4 parameters are covered, and the tool's complexity is fully addressed with clear examples ('Pipeworx', 'OpenInvoice').

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 enhances understanding by providing context for the default model and how _apiKey is used (passed straight through). This adds meaning 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 uses a specific verb ('Probe') and clearly identifies the resource ('LLMs') and the scoring objective. It distinguishes itself from siblings by emphasizing visibility scoring for AI-marketing audits, pre-launch brand checks, and competitive monitoring.

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

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

The description provides clear when-to-use context (AI-marketing audits, pre-launch checks, competitive monitoring) and explains when the optional _apiKey is needed. However, it does not explicitly mention alternatives (e.g., 'scan_competitor_ai_presence') or conditions to avoid using this tool.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive safety. The description adds meaningful behavioral detail: it routes across thousands of tools, fills arguments automatically, and returns structured answers with stable citation URIs. It does not mention limitations or failure modes, but the annotations carry the main safety burden.

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

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

The description is front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and is organized into scope, behavior, usage triggers, examples, and sibling routing. It is longer than strictly necessary and somewhat repetitive about web search preference, but every major sentence contributes to agent decision-making.

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

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

For a simple one-parameter tool with rich annotations and simple schema, the description provides enough context to invoke it correctly: when to use it, what it returns, and where to route complex queries. It does not differentiate ask_pipeworx_beta or ask_pipeworx_grounded, but the core usage is fully specified.

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 the single 'question' parameter and its aliases at 100% coverage. The description goes beyond the schema by providing trigger verbs and six concrete example questions, which help the agent understand the expected phrasing and scope. No additional formatting constraints are needed.

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 precise action: it routes a natural-language question to one of 5,743 tools, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It clearly distinguishes itself from generic web search and names relevant alternatives like deep_research, while the example domains make its scope unmistakable.

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

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

The description explicitly says to prefer this tool over web search, lists trigger phrases such as 'look up' and 'get the latest', and explicitly routes broad multi-part questions to deep_research. This gives an agent clear conditions for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond this: it is an experimental router with live candidate testing, currently identical to the stable version, and it is a fully functional router rather than a fallback stub. It could mention more about possible behavioral differences when a candidate is active, but the experimental nature is clearly implied.

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

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

The description is well-structured: core identity first, current state second, usage guidance third, and a brief reassurance about being a full router. It is concise, though the specific retirement date detail adds slight verbosity without significantly improving agent understanding. Each sentence generally earns its place.

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

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

For a complex universal router, the description provides sufficient context: it is a full router, currently identical to ask_pipeworx, accepts the same arguments, and returns the same response shape. Since there is no output schema, referencing ask_pipeworx's response shape fills the gap. It does not enumerate the 5,743 tools, but that is unnecessary for invoking the tool correctly.

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

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

The input schema has 100% coverage with each parameter described as an alias for the 'question' field. The description only says 'same arguments' and 'use it exactly like ask_pipeworx,' which does not add specific semantic detail beyond the schema. Since the schema fully documents the parameters, a baseline score of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of the ask_pipeworx universal router, specifying that it has the same 5,743 tools, arguments, and response shape. It explicitly distinguishes itself from the stable ask_pipeworx sibling by highlighting its experimental role and current equivalence. This is a specific, non-tautological statement of purpose.

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

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

The description explicitly instructs the agent to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It names the alternative (ask_pipeworx) and gives a clear selection condition, while also noting that no candidate is currently active so behavior matches the stable version. Nothing is left to inference.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the grounding mechanism: answers are extracted using ONLY the tool result, and it enumerates the exact refusal reasons when the data doesn't directly answer. The extra LLM call cost is also a transparent behavioral trait not visible in annotations.

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

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

Each of the five sentences earns its place: mode definition, routing mechanism, return shape, usage trigger, and cost trade-off. The purpose is front-loaded, and there is no filler or repetition of schema fields.

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 specifies both the success return object and the refusal return object with all refusal_reason enum values. It also covers the alternative tool and the selection condition. An agent has everything needed to invoke this tool correctly.

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

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

The input schema already documents the question parameter and aliases with 100% coverage, so the baseline is 3. The description adds meaningful context by explaining that the question drives routing and argument-filling across 5,743 tools, which tells the agent how the parameter is actually used beyond a simple string.

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 purpose: a 'hallucination-resistant answer mode for high-stakes reads' and then details the full pipeline from routing to extraction. It explicitly differentiates from the sibling 'ask_pipeworx' by positioning this as the grounded alternative and mentioning the trade-off ('prefer ask_pipeworx for casual 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?

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also names the alternative and specifies when to choose it ('prefer ask_pipeworx for casual lookups'), leaving no ambiguity about selection.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: resolution and classification process, fan-out to data packs, response shapes with statuses like 'low_confidence_match' and 'market_closed_or_inactive', tradeability warnings, and cancellation rule parsing. 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 very long and detailed, covering many aspects in multiple paragraphs. While front-loaded with the key purpose, it becomes verbose with detailed examples and edge cases. It could be more concise by using bullet points or structuring information more efficiently, but it remains informative.

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

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

Given the tool's complexity (researching bets across many categories, no output schema), the description is remarkably complete. It explains resolution, classification, fan-out, response fields, safety mechanisms, closed markets, wide spreads, and cancellation rules. It tells the agent what to inspect before trusting (market_match_confidence) and provides examples for various scenarios.

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. The description adds value by providing concrete examples for 'market' (slug, URL, question text), explaining 'depth' as quick vs thorough, and clarifying when to set 'include_raw' to true (recompute deltas, post-process). This 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 that the tool researches a Polymarket bet by pulling Pipeworx data, with specific inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It lists classifiers and fan-out examples, but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, though the scope is evident.

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 usage contexts: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also gives detailed guidance on inspecting market_match_confidence before trusting analysis, checking parent_event for elections/championships, and considering cancellation_rule before sizing. This is comprehensive and directly tells the agent when and how to use the tool.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. Description adds detail about what data is fetched (10-K metrics for companies, FAERS/trial data for drugs), sorting behavior, and citation URIs. No contradictions; description enriches the annotations.

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

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

Description is fairly long but every sentence adds value. It front-loads with example queries and key usage instruction. Could be slightly trimmed without losing clarity, but current length is justified by the depth of information.

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

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

Despite no output schema, description clearly states what is returned (paired data + citation URIs) and explains sorting. Covers both entity types and addresses behavioral expectations (e.g., off-calendar fiscal year handling). Leaves no significant gaps for a comparison tool.

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

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

Schema coverage is 100%, but description adds critical context: explains 'type' enum values map to specific data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), clarifies 'values' as tickers/CIKs or drug names, and notes max/min constraints. Goes 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?

Description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs. It provides example user queries and distinguishes itself from single-entity lookups like entity_profile. The verb+resource pairing is specific and unambiguous.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. Provides example phrases and outlines the scenarios for each type (company vs. drug). No confusion about alternatives.

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

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

Annotations already mark it readOnly, openWorld, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: account requirements, gap recovery behavior, contradictions[], citation semantics, the no-invention guarantee, excerpting behavior for large records, and latency expectations. This gives an agent an unusually complete picture of the tool's runtime behavior.

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

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

The description is long but information-dense; nearly every sentence adds a distinct, useful fact such as alternative-tool routing, deep-tier behavior, citation properties, and latencies. It is not perfectly front-loaded because the account-required notice appears before the main purpose statement, but the structure 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?

With no output schema, the description carries the duty of explaining what the agent will receive. It thoroughly covers the findings packet fields, gaps[] and contradictions[] arrays, citation URIs, and timing. Combined with the rich annotations and complete parameter schema, an agent has enough context to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the input schema already documents both parameters well. The description reinforces the difference between depth modes and adds notes like 'thorough needs a paid plan' and latency expectations, but it does not substantially change parameter understanding beyond the schema's own 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 states a specific verb and resource ('Grounded multi-source research across Pipeworx's 1500 STRUCTURED data sources... in ONE call') and clearly distinguishes itself from open-web search and from ask_pipeworx. It also describes the internal mechanism of decomposition and parallel routing, leaving no ambiguity about what the tool does.

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

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

It explicitly says when to use this tool ('Best for broad/multi-part questions over structured data'), when not to ('For a single lookup use ask_pipeworx'), and even names a fallback for unsigned-in users. The depth tiers are explained with concrete behavioral differences, giving clear decision criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return behavior: returns top-N tools with full schemas and examples, ready to call directly. 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?

Description is well-structured, front-loading purpose, listing domains, then return format and usage advice. Every sentence adds value, though slightly long.

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 comprehensively explains return value (names, descriptions, full schemas with examples). Parameters fully covered. Complete for a discovery 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% with clear parameter descriptions. Description adds context that limit controls top-N and that result includes schemas, going 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 clearly states it finds tools by describing data or task, listing specific domains. It distinguishes itself as the discovery tool to call first, unlike siblings which are individual tool functions.

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

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

Explicit guidance on when to use: for browsing/searching/discovering tools, and 'Call this FIRST' with many tools. Missing explicit when-not-to-use or alternatives, but clear 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive; the description adds far more: the multi-source fan-out, sources_used/sources_failed semantics, patents API sunset soft-fail, GDELT→GNews fallback, and the explicit 'empty is real no-data, not a bug' guidance. This is exactly the behavioral context an agent needs and cannot infer from annotations alone.

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

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

The description is dense but rambling, containing a garbled fragment ('Note: EDGAR submissions (FilingSummary) — that's expected;') that is confusing and breaks the flow. Several caveats about empty results are repeated across sentences, making the structure less crisp than it could be for such a long definition.

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 two parameters and no output schema, the description carries the burden of explaining return values, and it does so thoroughly: the exact fields returned, URI format for filings, sources_used/sources_failed distinction, per-source caveats, and fallback chains. The only notable gap is the unclear EDGAR submissions note, which leaves ambiguity about what 'expected' refers to.

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

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

The schema already covers both parameters 100%, and the description adds meaningful clarification: type and value are interchangeable, value can be a ticker, zero-padded CIK, or company name, and name resolution occurs via SEC EDGAR. The description also explains what happens for unresolved private companies, extending parameter semantics beyond the raw schema.

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

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

The description is anchored by concrete user intents ('Tell me about X', 'research Acme', 'brief me on Tesla') and defines the tool as a 'full cross-source profile of a US public company in ONE parallel call'. It clearly names the operation and resource, and the 'ALWAYS PREFER' line distinguishes it from single-source SEC/XBRL/news 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?

It explicitly tells the agent to prefer this tool over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, which is a strong when-to-use signal. It also explains input acceptance and the private-company resolved:false behavior, but it does not explicitly name sibling tools like deep_research or compare_entities as alternatives one should consider instead.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description confirms the destructive nature (delete) but adds no further behavioral details beyond what annotations indicate. 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?

The description is concise (three sentences), front-loaded with the core action, and every sentence adds value—no filler or redundancy.

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

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

For a simple tool with one parameter and no output schema, the description provides complete context: what it does, when to use it, and how it relates to siblings. Annotations cover the rest.

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

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

Schema coverage is 100%, so the schema fully documents the 'key' parameter. The description does not add additional meaning beyond the schema's 'Memory key to delete', so baseline 3 applies.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key', distinguishing it from sibling tools like 'remember' and 'recall' which store and retrieve memories respectively.

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 usage guidance is provided: 'Use when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', effectively directing the agent on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds process details (fetches page, extracts title/description/key links, emits markdown) beyond annotations, but does not contradict 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?

Three concise sentences: purpose, process, use cases. No redundant words. Information is front-loaded.

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

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

For a simple generation tool with two parameters and no output schema, description adequately explains what it does and outputs. Could optionally mention error cases, but not required.

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

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

Schema description coverage is 100% for both parameters. Description does not add additional parameter meaning beyond what schema provides, so baseline 3 is appropriate.

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

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

Description clearly states verb (generate), resource (llms.txt file), and context (for AI crawlers). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation.

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

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

Provides explicit use cases (client's site indexing, own project drafting, competitor auditing). Lacks explicit alternatives or when-not-to-use, but the sibling list implies other related tools are available.

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, openWorldHint, and destructiveHint. The description adds behavioral context: it returns active subscriptions by default, with an optional include_inactive parameter, and lists the specific fields returned. This adds value beyond the annotations.

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

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

Two sentences with no waste. First sentence states purpose and return fields, second gives usage guidance. This is an ideal structure.

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 is complete. It explains what it returns and when to use it. No output schema is needed because the return format is clearly 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?

Schema coverage is 100% with one parameter fully described. The description doesn't add additional meaning beyond what the schema already 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 'List the caller's active subscriptions' with specific verb and resource. It lists return fields and distinguishes from siblings 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?

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for when to use it, though it doesn't explicitly mention when not to use it.

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

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

Discloses important behavioral details beyond the annotations: filing returns a claim_token for later retrieval, rate-limited to 5 per identifier per day, free and not quota-counted, and advises describing issues in terms of Pipeworx tools/packs. 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 longer than average but each sentence contributes: purpose, use cases, exclusions, guidance on content, claim_token mechanics, rate limits, and impact. It is front-loaded with the core action and well-organized, 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?

Despite lacking an output schema, the description tells the caller what to expect (claim_token for new filings, status updates when passing the token again). It covers prerequisites (no account needed), rate limits, scope boundaries, and team read cadence. Complete for a feedback 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 covers all 4 parameters at 100%, so baseline is 3. The description adds semantic value by explaining the claim_token lifecycle in detail: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed.' This goes beyond the schema's dry parameter description.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies distinct use cases (bug, feature, data_gap, praise) and differentiates itself from sibling tools by focusing on feedback for Pipeworx tools, not on asking questions or research.

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

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

Provides explicit when-to-use guidance with concrete examples ('Use when a tool returns wrong/stale data (bug)...'). Also gives strong when-not-to-use instructions: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' Offers a heuristic for uncertainty: 'Pipeworx tool names are the ones this connection lists.'

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 valuable details: data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h depending on window. No contradictions.

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

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

The description is concise with three sentences plus a bulleted list. It is front-loaded with the main output and zero wasted words.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, usage, behavioral details, and parameter semantics comprehensively. It leaves no gaps.

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

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

Schema coverage is 100% with enum descriptions. The tool description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances 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, packs, and call volume over a recent window. It uses specific verbs and resources, distinguishing it from siblings like discover_tools by focusing on trending data derived from AI agent calls.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and explains window tradeoffs. It does not explicitly mention when not to use or alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds transparency about fill_check, Jaccard similarity filtering, partition placeholder filtering, and response structure. 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?

Well-structured with sections and examples, but somewhat lengthy. Front-loaded with purpose. Could be slightly more concise while retaining essential detail.

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

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

Despite no output schema, description fully explains response structure (opportunities[], partition_check fields, fill_check details). Covers edge cases like Jaccard similarity, placeholder filtering, and fill_check pricing. Complete for a complex tool with 2 optional 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?

Schema has 100% coverage with descriptions for both event and topic. Description adds significant meaning: explains what each mode does (walks child markets, computes partition_check for event; searches related events across platform for topic) and provides example inputs. Enriches beyond schema but schema already carries its weight.

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

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

Description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection using specific algorithms.

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 each parameter: NO args for trending_scan, event for specific market, topic for cross-event scanning. Includes recommendations (event recommended) and warnings about fill_check and not trading when realizable_edge_pp ≤ 0.

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 annotations by explaining data sources (FRED, GDELT), model families, caching (1h at KV level), tradeable-edge knobs, and diagnostics for empty segments. It fully discloses behavioral traits like the exclusion of Fed markets and the detailed scoring logic, with no contradictions to 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 detailed and well-structured with segments, but it is quite long. Every sentence adds value given the tool's complexity, though a more structured format with clear sections could improve scannability.

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 thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and the meaning of fields like edge_pp_net, kelly_fraction, and 24h-move warning. It covers all key aspects needed for proper usage, making it complete for a complex tool.

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

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

Input schema covers all 9 parameters with descriptions (100% coverage). The tool description adds extra context, such as slippage_pp noting Polymarket fee structure and min_partition_leg_kelly explaining why min_kelly doesn't apply to partition arbs, enhancing understanding beyond the schema.

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

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

The description clearly states it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from siblings by detailing unique model families and segments, making its purpose unambiguous.

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

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

The description provides guidance on when to use (discovery without paging hundreds of markets) and mentions exceptions (Fed markets excluded from ranking due to unreliable signal). However, it does not explicitly compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about 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?

Adds extensive behavioral context beyond annotations: explains data source (daily snapshots), return structure (tracked, expired, snapshot_dates), decay computation methodology, and limitations (not intraday). Annotations already indicate read-only, but description enriches understanding.

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?

Relatively dense but each sentence adds unique value. Could be slightly more concise (e.g., avoid repeating 'snapshots' multiple times), but front-loads purpose and key concepts effectively.

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 fully explains all return fields (tracked, expired, snapshot_dates) and their subfields (trend, decay, lifespan). Also covers limits and data source details. Highly complete for a tool with two optional parameters.

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, but description adds value: specifies default and clamp range for 'days' and default value for 'window', plus notes about response fields that depend on parameters. Justifies a 4.

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

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

Clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering a specific trading question about edge age and decay. Distinguishes from sibling 'polymarket_edges' by focusing on time-series analysis.

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 (e.g., comparing fresh vs. old wide edges) and mentions limits like 60-day TTL. Does not explicitly state when not to use or name alternatives beyond 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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond annotations: it explains basket fill risks (thin legs, forced directional risk), return fields (verdict, capture_ratio, max_clean_notional), and the dominant loss mode from partial fills. This is rich context, though the density slightly reduces clarity.

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

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

The description is dense but not wasteful; every sentence adds unique information. It front-loads the core purpose and mode distinction. However, the length (especially the basket detail) could be more structured (e.g., using bullet points) to improve scannability while maintaining completeness.

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

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

Given the tool's complexity (two operation modes, financial risk implications, no output schema), the description is remarkably complete. It enumerates all key return fields (top_of_book, vwap_fill_price, slippage, per-leg fill detail, verdict, etc.) and explains failure modes. The agent has sufficient information to understand outputs and risks.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the interpretation of size_usd (spend vs target proceeds for single-market, settlement notional for basket) and explaining the auto side logic for baskets. This goes beyond the schema's descriptions, justifying 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?

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', identifies two distinct modes (single-market and basket), and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill feasibility rather than signal generation.

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

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

Explicit when-to-use guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (theoretical overround on thin books, partial fills converting arb to directional risk), effectively steering the agent toward this tool and away from alternatives.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive; the description goes far beyond that with dense behavioral disclosures: it does not model Kalshi fees, spreads are gross not net, temporal_alignment null means uncomputed rather than aligned, unknown metric_type legs are never paired, and compatibility flags can be non-empty even when pairs are returned. This is exemplary transparency for a complex data tool.

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 almost every sentence carries a distinct safety or matching detail, and the opening sentence front-loads the purpose and scope. It could be better organized with bullets or clearer section breaks, but there is no filler or tautology; each clause 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?

With no output schema, the description fully compensates by explaining the response shape: leg-by-leg prices, spread[].top_spreads_pp, compatibility codes, per-entry flags, skipped_unclassified, low_confidence_pairs, temporal_alignment, fees_note, and skipped counters. Edge cases and failure modes are covered, making the tool invocable and interpretable without additional sources.

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 three parameters at 100% coverage, so the baseline is 3. The description adds meaningful behavior: topic auto-fetches matching events on each venue, explicit ticker/slug overrides the mapped side, and both modes run the identical token-overlap matcher. That enriches parameter understanding beyond the schema definitions.

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

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

Opens with a specific, resource-scoped statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names both venues, the comparison type, and the core outcome, and further clarifies scope by distinguishing topic shortcuts from explicit pairings. The purpose is unmistakable and distinct from sibling tools like polymarket_arbitrage or 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?

Provides clear usage context through TWO MODES, explicit parameter options, and warnings like 'pre-mapped ≠ tradeable' and 'most pre-mapped topics return compatibility_warning today.' It does not explicitly name alternatives to use instead, so it stops short of a full when-to-use vs. when-not-to-use guide, but the mode routing and caveats give an agent strong operational 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms read-only behavior (retrieve/list) and adds scoping info. 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?

Three concise sentences front-loaded with purpose. Every sentence adds value: core function, contextual usage, and relationship with siblings.

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 (one optional param, no output schema, rich annotations), the description fully covers usage, scoping, and sibling relationships. No gaps.

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

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

Schema coverage is 100% with a single optional key parameter. Description adds clear semantics: provide key to retrieve specific value, omit to list all keys. Goes beyond schema by explaining the dual behavior.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys. It distinguishes itself from siblings (remember, forget) by specifying the retrieval and listing behavior.

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

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

Provides explicit guidance on when to use (look up stored context without re-deriving) and how to use (omit key to list all). Mentions scoping and pairing with remember/forget, offering clear context and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about mark_read affecting subsequent calls and confirms the feed is persisted. No contradictions; adds useful behavioral detail 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?

Three sentences front-load purpose and return details. Each sentence adds information without redundancy. Could trim 'the same feed is also at...' as it's an alternative not essential for usage.

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

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

For a read-only tool with no output schema, description adequately covers what is returned (source, citation_uri, payload) and mentions alternative endpoint. Missing explicit return structure details (e.g., pagination) but sufficient given simplicity.

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

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

All 5 parameters are already described in schema (100% coverage). Description adds value with concrete examples ('e.g. 'sec_8k') and clarifies mark_read's effect on future calls, providing context not in 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 clearly states it pulls fired events from a subscription feed, specifying return fields (source, citation_uri, payload). However, it does not explicitly differentiate from sibling tools like list_subscriptions or the direct GET endpoint, though the distinction is implicit.

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 guidance on polling ('Polls work fine') and explains when to use mark_read to avoid re-reading. Mentions an alternative access method (GET registry.pipeworx.io/alerts.json), but does not explicitly contrast when to use the tool versus 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, destructiveHint=false, and openWorldHint=true. The description adds behavioral details beyond annotations: fans out to SEC, GDELT/GNews, USPTO with soft-fail, and describes output structure (changes[] grouped by source, total_changes count, citation URIs). 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?

The description is concise (about 100 words) and front-loaded with user intents. Every sentence adds value, with no redundancy or wasted words.

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

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

Given the tool has 3 parameters with thorough schema descriptions, no output schema, and safety annotations, the description adequately explains the multi-source behavior, fallback, and return structure (changes[] grouped by source, total_changes count, citation URIs). It could mention pagination or limits but is sufficient.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by clarifying that 'since' accepts ISO date or relative shorthand (e.g., '7d', '30d', '1y'), suggests '30d' or '1m' for typical monitoring, and explains that 'value' can be a ticker or zero-padded 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 clearly states the tool provides a change feed for a company over a recent window, with explicit user intents like 'What's new with X' and 'latest on Y'. It distinguishes from sibling tool 'entity_profile', which is for static profiles.

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

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

The description provides explicit when-to-use guidance (change feed queries) and when-not ('Use entity_profile instead for static profile'). It also explains the fallback mechanism between GDELT and GNews and gives examples of the 'since' parameter format.

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

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

Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds key behavioral details: scoped by identifier, persistence (24h for anonymous users). 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?

Five sentences, front-loaded with purpose. Every sentence adds value (when to use, how storage works, pairing with other tools). No fluff.

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

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

Given simple parameters (key, value) and no output schema, the description fully covers storage, retrieval, deletion, scoping, and persistence. No gaps.

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

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

Schema coverage is 100%, so baseline 3. Description enriches with usage context (key as identifier like 'subject_property', value as findings) beyond schema labels, justifying 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?

The description clearly states the tool saves data for reuse across conversations/sessions and gives concrete examples (resolved ticker, target address). It distinguishes from siblings like 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 mentions pairing with recall/forget. Lacks explicit 'do not use' scenarios 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 declare readOnly/openWorld/idempotent/non-destructive. The description adds substantial behavioral context beyond that: ambiguous names return figi_candidates without asserting a single answer, unresolved identifiers are listed explicitly, enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, and identifiers are source-labelled. 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 densely informative, with front-loaded usage examples and trigger phrase. It is organized into supported types and caveats, and nearly every clause carries operational value rather than filler.

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

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

With no output schema, the description carries the return-value burden, and it delivers: it mentions figi_candidates, unresolved identifiers, source labels, drug RxCUI citations, and fallback behavior. It also covers input edge cases and failure modes, making the tool safely callable by an agent.

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

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

Schema coverage is 100%, but the description goes well beyond schema names and enum lists. It clarifies accepted input formats per entity type, explains ISIN-to-LEI behavior, and gives critical guidance such as passing only the issuer name rather than the full noun phrase for bond lookups. This materially improves invocation correctness.

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 and resource: resolve a user-spoken name into canonical/official identifiers that other tools require as input. It distinguishes itself from sibling tools by framing the core value as name-to-ID lookup and enumerating supported entity types.

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 an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups. However, it does not name specific sibling alternatives or state when not to use it, such as when an ID is already known and an entity profile is needed.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and signal density. No contradictions.

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

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

Two concise sentences: first covers core action and output, second gives use case and example. No unnecessary words. Very 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?

The description explains the transformation (calling ai_visibility_check, ranking) and output format (ranked list with metrics). It notes the first entity as subject. Lacks exact output structure but is sufficient for an agent to infer. No output schema, so description carries weight, but it is reasonably complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about how parameters are used (e.g., first entity as subject, probes per entity), which provides moderate added value 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 the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes from siblings like ai_visibility_check by specifying multi-entity comparison. The use case is explicitly given.

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 explains that the tool is useful for competitive AI-marketing audits and provides an example. It implicitly tells when to use it instead of calling ai_visibility_check multiple times. However, it does not explicitly state when not to use or list alternative tools, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes beyond: 'Partial failures degrade gracefully', 'bundlephobia's first measurement on a new version can take 5-30s', and mentions 'sources_failed' list. No contradictions.

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

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

The description is dense but front-loaded with the purpose. It uses one long paragraph which could be more structured, but every sentence is informative and earns its place.

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

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

Given the composite nature, no output schema, and rich annotations, the description is extremely complete: explains return structure (summary block, advisories, links, alternatives), partial failure, ecosystem limitations, and timing caveats.

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 both parameters (package, version) with descriptions. The description adds clarity: 'Scoped packages (e.g. "@types/node") are accepted' and 'Defaults to the latest published version when omitted.'

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 composite purpose: checking if an npm package should be added to a project, using deps.dev and bundlephobia. It specifies the verb ('check'), resource (npm package), and distinguishes from siblings (e.g., 'NPM ecosystem only in v1').

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" or "what does adding lodash cost me".' Also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details using BGE-base-en embeddings, cosine similarity over 500-char windows, a 200K char limit with truncation flag, and offsets for verification. 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, well-structured paragraph. First sentence front-loads the purpose. Every sentence adds value: use case, pairing, technical details, limits. No fluff.

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

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

Without an output schema, the description fully explains return values (top-N passages with offsets and similarity scores) and limitations (200K char cap with truncation flag). Complete for a tool with 3 parameters and no output schema.

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

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

Schema coverage is 100% with descriptions for all params. The description adds context by explaining the workflow (pass text you already pulled plus query, get back passages). This reinforces and elaborates on the schema, moving beyond baseline 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article). It distinguishes itself from siblings by mentioning how it pairs with ask_pipeworx_grounded, and the purpose is explicit and unique.

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

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

Explicitly says to use when the record is too large for the prompt, and explains how it saves context. Mentions pairing with a sibling tool, providing clear guidance on when to 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, openWorldHint=true), the description adds critical behavioral details: authentication requirements (Pipeworx OAuth account), SMS cap (10/day), webhook auto-disable after 10 failures, and that the webhook signing secret is returned once. 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 efficiently structured: front-loaded with the main action and return value, followed by essential prerequisites, then type and delivery details. Every sentence provides necessary context 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?

Given the tool's complexity (3 params with nested objects, multiple types and delivery channels), the description covers authentication, type-specific filters, and delivery constraints. It explains the return value ('new subscription id'). Minor gap: idempotency behavior not clarified despite idempotentHint annotation.

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?

Despite 100% schema coverage, the description enriches parameter understanding with concrete examples for each type (e.g., items codes for sec_8k, topic for polymarket_edge) and delivery constraints (phone verification, cap). This adds value 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 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb ('Create') and resource, distinguishing it from sibling tools like 'unsubscribe' and 'list_subscriptions'.

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

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

The description provides explicit context for when to use the tool (to create subscriptions) and details supported types and delivery channels. However, it does not explicitly state when not to use it or mention alternatives beyond the implicit sibling set.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds behavioral context by stating it returns category-bucketed example questions with exact tool+argument shapes from the live catalog, which provides additional transparency beyond the annotations.

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

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

The description is relatively long but well-structured, starting with synonyms/questions the tool can answer, then describing the output, and ending with usage guidance. It is front-loaded with the core purpose and effectively communicates without excessive 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?

Given the low complexity (one optional parameter, no output schema), the description is highly complete. It explains the output format, usage in onboarding, optional topic filtering, and even mentions related meta-tools. The description fully equips the agent to use 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?

Schema coverage is 100% with a single optional parameter. The description adds meaning by listing specific focus area options (finance, pharma, etc.) and explaining the effect of omitting the parameter (full spread), which goes beyond the schema's brief description.

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

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

The description clearly defines the tool as the onboarding entry point for an agent that just connected, returning category-bucketed example questions. It distinguishes itself from siblings by being the first tool to use when learning about Pipeworx's capabilities.

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 to use this tool FIRST when you do not yet know what Pipeworx can do. It also provides guidance on optional topic filtering and mentions that it teaches how to call meta-tools. It lacks explicit when-not-to-use guidance but is clear overall.

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, so the description carries less burden for safety. It adds value by detailing the return fields (greeks, open interest, etc.) and provides an example call, which helps agents understand expected output.

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

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

Description is two sentences plus an example, perfectly front-loaded with the core purpose. Every sentence adds value, and the example clarifies usage. No wasted words.

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

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

Given no output schema, the description adequately explains what is returned (all calls/puts, bid/ask/last, volume, open interest, greeks). The example further helps. Could mention pagination or rate limits, but overall sufficient for most use 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?

Schema coverage is 100%, so all parameters are already described in the input schema. The description adds an example and reiterates the _apiKey and expiration format, but does not provide new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states the tool retrieves an option chain for a given symbol and expiration, and lists the specific data returned (strikes, greeks, IV, open interest, bid/ask/last, volume). This distinguishes it from sibling tools like tradier_quote (single quote) and tradier_option_expirations (list expirations).

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 when to use (when you need full option chain data for a specific symbol and expiration). However, it does not explicitly mention when not to use or provide direct alternatives. Given the clear sibling tool names, this is still effective guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, which accurately describe the tool's safety. The description adds minimal behavioral information beyond the annotations, such as the return format, but does not contradict 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?

Two concise sentences and an example, with the action verb front-loaded. Every sentence serves a purpose, 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 explains the return format (array of YYYY-MM-DD dates) and its downstream use, which is adequate for a simple list tool. However, it does not mention error cases or what happens if the symbol has no options.

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

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

Schema coverage is 100%, so the description adds little new meaning. It includes an example showing symbol and _apiKey, but the schema already explains their purpose. The sandbox parameter is shown but not described. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists available option expiration dates for a symbol, with a specific verb 'List' and resource 'option expiration dates'. It distinguishes itself from siblings like tradier_option_chain and tradier_quote by specifying that the output is an array of dates to be passed to the chain.

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

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

The description suggests a sequential usage pattern by stating the output can be passed to tradier_option_chain, but it lacks explicit guidance on when to use or not use this tool, and does not mention prerequisites or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail by specifying the returned data (last price, bid, ask, volume, change), which goes beyond the structured annotations. 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 plus an example with no wasted words. The first sentence immediately states the purpose and key data fields. The example is concise and demonstrates usage with realistic data.

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

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

Given the tool's simplicity and lack of output schema, the description covers essential information: what the tool does, input format (comma-separated symbols), and example. It could mention error handling or rate limits, but for a real-time quote tool it is mostly 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% with clear descriptions for all parameters. The description reinforces the parameter behavior (e.g., 'comma-separated tickers') and provides an example, but does not add significant new meaning beyond the schema. Baseline score of 3 applies.

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

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

The description clearly states 'Get real-time quotes' and lists specific data fields (last price, bid, ask, volume, change). It distinguishes from siblings like tradier_option_chain and tradier_option_expirations by focusing on real-time price quotes for equities.

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

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

The description provides a clear purpose but lacks explicit guidance on when to use this tool versus alternatives (e.g., for options data use tradier_option_chain). The example shows usage but no exclusions or context like 'use for intraday pricing, not historical'.

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?

Describes beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' Annotations already indicate mutation (readOnlyHint=false) and idempotency, but description adds critical soft-delete behavior.

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

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

Two sentences, zero wasted words. Main action first, then additional details in a natural flow.

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

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

For a simple tool with 1 param, no output schema, no nested objects, the description fully covers input, behavior, side effect, ownership constraint, and post-effect (data still available via recent_alerts).

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?

For the single 'id' parameter, the description adds 'Subscription id (uuid) returned by subscribe' which tells where to get the value. Schema already describes it as a uuid, so description adds provenance 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?

Clearly states 'Cancel a subscription by id' (specific verb+resource), and distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and the deactivation effect.

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 (with a subscription id) and the ownership constraint. Lacks explicit when-not-to-use or alternatives, but the sibling list provides 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 declare the operation read-only/idempotent/non-destructive; description adds substantial behavior: structured XBRL fast path, automatic fallback to grounded pipeline, exact percent-delta math, verdict vocabulary, citation format, and the crucial could_not_verify vs unsupported distinction with verification_error{stage,detail}. This goes well beyond annotation hints.

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

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

The description is longer than typical but every section earns its place: triggers, usage rule, two execution paths, return contract, and caller warning. It is front-loaded with examples and structured by function, though a heading or shorter final sentence could tighten it.

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

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

Despite having no output schema, the description fully specifies the return value (verdict choices, grounded/structured value, citation, reasoning) and failure semantics. It also covers both input params, the tolerance override, and the unsupported vs could_not_verify distinction, making it self-sufficient for a high-complexity 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 already documents both parameters with 100% coverage, so baseline is 3. The description adds meaning by explaining tolerance_pct's role in hallucination detection (1–2) and its default/cap, and by clarifying that claim is free-form natural language with examples. This extra context justifies a 4.

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

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

Description explicitly frames the tool as claim verification with trigger phrases ('Is it true that…', 'fact check'), specifies a concrete resource (authoritative sources), and distinguishes it from sibling research/ask tools by focusing on true/false judgment with a verdict. The two-path description (SEC EDGAR vs grounded) further pins down scope.

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

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

Gives an explicit use condition ('Use whenever the agent needs to check whether something a user said is factually correct') and differentiates handling by claim type (company-financial vs other). It does not name specific sibling tools to avoid, but the trigger-based guidance and edge-case instructions ('could_not_verify... not evidence') give clear operational direction.

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