Rxnorm

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

Annotations already provide readOnly, idempotent, openWorld, non-destructive hints. The description adds crucial behavioral context: cost implications ('you pay Anthropic directly'), default model selection, and the exact return structure (per-model score, confidence, signals, raw_response + 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 concise (four sentences) and front-loaded with the primary action and result. Every sentence adds unique value: purpose, default/optional behavior, output format, and use cases. No wasted words.

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

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

Given the tool's moderate complexity (4 parameters, no enums, no output schema), the description fully covers what the tool returns, how to use optional features, and typical use cases. It leaves no critical 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 is 3. The description adds value by explaining default model behavior, the relationship between `_apiKey` and `models`, and the purpose of `context`. It also reveals the return format, which is not in 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 action ('Probe one or more LLMs') and the object ('what they know about a business / brand / product / topic') with a specific deliverable ('score visibility 0-100 per model'). It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on multi-model scoring and branding audits.

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 use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It also notes the default free model and optional paid Anthropic probe. However, it does not explicitly state when not to use this tool versus siblings, which would be helpful.

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

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

Annotations already mark the tool as read-only, open-world, and idempotent. The description adds valuable behavior beyond that: the tool acts as a router that fills arguments automatically and returns structured answers with stable 'pipeworx://' citation URIs. This gives the agent a meaningful picture of what invoking the tool will do, without contradicting any annotation.

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

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

The description contains significant duplication: the 'Use whenever...' sentence, the example list, and the 'START HERE' phrase are repeated, and the ending trails off with a garbled fragment. While the opening is informative and front-loaded, the redundancy and lack of editing make it harder to parse than it should be.

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 router tool with no output schema, the description is quite complete: it lists covered domains, gives concrete example queries, explains the routing and citation behavior, and clearly positions the tool as the default starting point. It lacks only a fuller treatment of exclusions or sibling differences, which keeps it below a 5.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and their aliases. The description does not add parameter-level detail beyond providing example questions, which is somewhat helpful but not essential given the schema's clarity. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a general factual question router: it 'Routes the question to the right one of 5,798 tools across 1517 verified sources' and returns structured answers with citations. It is not tautological and gives concrete examples, but it does not differentiate itself from closely related siblings like ask_pipeworx_beta or ask_pipeworx_grounded.

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

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

The description states explicitly when to use this tool: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'Use whenever the user asks... even if web search could also answer it.' It also says 'START HERE for most questions,' giving a clear default. However, it does not explicitly list when-not-to-use scenarios or alternatives among the sibling tools.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing live candidate testing, the current inactive state (last candidate retired 2026-07-26), temporal equivalence with the stable router when no candidate is active, and that it is a complete working router rather than a stub ('Falls back to nothing'). This temporal behavioral context is exactly what an agent needs and is not available from structured fields. 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?

Four sentences of dense, front-loaded content: identity and scope in sentence one, current candidate state in sentence two, usage instruction in sentence three, and a functional guarantee in sentence four. Each sentence contributes distinct information; the final emphatic sentence is slightly redundant but guards a real misconception about beta tools.

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 fully handles the tool's main complexity — the live candidate-testing behavior and its current state — and confirms the response shape matches ask_pipeworx, which is a reasonable delegation. However, the actual response shape is only referenced, not described, and there is no output schema to compensate, leaving the agent without concrete return-value detail.

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

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

Schema description coverage is 100%, with all 6 parameters (question plus 5 aliases) already documented in the schema. The description adds only the marginal note that arguments match ask_pipeworx exactly, which reinforces but does not meaningfully extend parameter understanding. The baseline 3 applies since the schema carries the full burden.

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

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

The description states a specific, concrete purpose: a universal router identical to ask_pipeworx (same 5,798 tools, same arguments, same response shape) with experimental candidate routing improvements. It clearly distinguishes itself from the stable sibling ask_pipeworx by framing itself as the beta/experimental edge, and reinforces that it is fully functional.

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 given: 'Use it exactly like ask_pipeworx when you want the newest routing,' naming the stable sibling as the comparison point and explaining results are evaluated against it for merges. However, it does not state when NOT to use it or address the ask_pipeworx_grounded sibling, so the exclusion guidance is incomplete.

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

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

The description goes well beyond the readOnly/openWorld/idempotent annotations by disclosing the refusal behavior, the exact return shape, and the refusal reason enum. It also establishes the ground-truth constraint: answers are extracted only from tool results, which is key behavioral context for an agent deciding whether to trust the 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?

The description is dense but efficient: it front-loads the mode and purpose, then gives routing behavior, output contract, use cases, and cost tradeoff. Slightly long, but each clause earns its place and no information is redundant with the annotations or schema.

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

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

For a grounding/refusal-capable tool with no output schema, the description is unusually complete: it specifies the success return fields, the failure shape, the possible refusal reasons, and when to prefer a cheaper sibling. An agent has everything needed to decide whether to invoke it and how to interpret the response.

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

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

Schema description coverage is 100%, with the single substantive parameter 'question' and its aliases fully documented in the schema. The description adds no extra parameter-level detail, so the baseline of 3 is appropriate because the schema already carries the semantic load.

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

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

The description names a specific mode — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the mechanism: it routes like ask_pipeworx, fetches data, then extracts the answer using only the tool result. This clearly distinguishes it from ask_pipeworx and other siblings by emphasizing grounded, evidence-based answering.

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

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

Explicitly states when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on' and gives concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative and the tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

The description extensively details behavioral traits such as resolution contract, parent event extractor, news fallback mechanisms, safety checks, and resolution-rule risk, far exceeding the sparse annotations.

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

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

The description is long but well-organized with clear sections and front-loaded purpose. Some redundancy exists but structure aids readability.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers all aspects: input formats, processing, response shapes, edge cases, and safety, making it highly complete.

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

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

Schema coverage is 100% with descriptions, and the tool description adds valuable context for each parameter (e.g., market input types, depth options, include_raw usage).

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 researches a Polymarket bet by pulling relevant Pipeworx data. It provides specific use cases and distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage.

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

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

Explicit usage scenarios are given ('should I bet on X', etc.), but no direct mention of when not to use it or alternatives, though siblings exist.

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

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

The description adds significant behavioral context beyond annotations. It details data sources (SEC EDGAR/XBRL, FAERS, FDA, clinicaltrials), explains how off-calendar fiscal years are handled, and clarifies that results are sorted by primary metric. This complements the readOnlyHint and other annotations without contradiction.

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

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

The description is front-loaded with natural language triggers and is well-structured. However, it is somewhat lengthy and could be slightly more concise without losing clarity. Still, every sentence adds value.

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

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

The tool handles two distinct entity types and multiple data sources. The description covers all essential aspects: input constraints, data sources, handling of fiscal years, sorting order, and return format (paired data + citation URIs). No output schema exists, but the description sufficiently explains the output.

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 adds essential meaning. It explains what data each type retrieves (e.g., 'LATEST 10-K revenue + net income + cash + long-term debt' for companies, 'FAERS adverse-event counts' for drugs). This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It uses specific verbs like 'compare', 'rank', and includes examples of natural language triggers. It distinguishes from sibling tools by explicitly stating it replaces 8-15 sequential lookups.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides concrete usage examples ('compare X and Y', 'which is bigger') and specifies the input constraints (2-5 entities). This clearly guides when to use 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?

Beyond the annotations (readOnly/openWorld/idempotent), it discloses auth requirements and paid tier, latency, non-open-web grounding, citation format with resolvable URIs, gaps[] never invented, contradiction scans, and semantic excerpting. 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 information-dense; it front-loads the account requirement and sibling fallback before the core explanation. Some redundancy with the schema's depth description could be trimmed, but every sentence adds operational guidance.

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

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

With no output schema, the description compensates by detailing the return packet's fields, the gaps[] behavior, citation URI resolvability, and failure semantics. For a 2-parameter tool with complex runtime behavior, this is 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 covers 100% of parameters, with depth enum fully described, so baseline is 3. The description adds value by tying 'thorough' to a paid plan, clarifying depth's hop behavior in prose, and giving latency expectations per depth.

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

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

States a specific verb ('research'), the resource (Pipeworx's 1,517 structured data sources), and the unique mechanism (decomposition, parallel routing, findings packet). It explicitly distinguishes itself from open-web search and names its sibling alternative, ask_pipeworx, so an agent can select it confidently.

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: broad/multi-part questions over structured data, with concrete examples. It also provides exclusions: not signed in → ask_pipeworx; single lookup → ask_pipeworx. This is model guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context: returns top-N results with full schemas and examples, ready to call directly. 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 two sentences, front-loading the purpose. The second sentence is long with many examples but remains informative. Could be slightly more concise, but is generally well-structured.

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

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

The description explains the output structure (top-N tools with names, descriptions, full schemas) and the intended use case (call first). With good annotations and no output schema needed, it covers essential information 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 description coverage is 100% with clear parameter descriptions and aliases. The description mentions the 'query' parameter as natural language, but does not add significant meaning beyond the schema. Baseline 3 is appropriate given high coverage.

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

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

The description uses specific verbs like 'browse, search, look up, discover' and lists numerous example domains. It clearly states the tool's function as finding tools by describing a data or task, and distinguishes it from siblings by recommending it as a first call to see the option set.

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

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

The description explicitly says when to use ('when you need to browse, search, look up, or discover what tools exist for...') and advises calling it first. It implies it is for discovery rather than direct answer retrieval, but lacks explicit when-not-to-use guidance.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: parallel fan-out across sources, soft-fail behavior for the USPTO patents sunset, expected-empty sections like fda_products, resolved:false handling for private companies, and the semantics of sources_used/sources_failed.

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

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

The description is long but every clause carries operational weight—input forms, output fields, source failures, and edge cases. It is front-loaded with the primary purpose and usage rule, and the rest of the detail is directly actionable 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?

There is no output schema, so the description correctly takes on the burden of explaining return values. It enumerates all major output sections and their semantics, explains failure modes, covers the no-data-versus-bug distinction, and describes all valid input shapes. An agent has everything needed to select and call 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 baseline is 3, but the description adds meaningful value: it documents zero-padded CIK formatting, gives concrete examples for ticker/CIK/name, and clarifies that type accepts 'company' or 'ticker' interchangeably with identical behavior. These are operational details an agent needs beyond the schema.

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

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

The description states a specific action: it produces a full cross-source profile of a US public company in one parallel call, supported by example user phrasings and a concrete list of what the tool returns. It also differentiates itself from single-source lookups by name ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'), making its purpose unmistakable.

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

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

It explicitly says to prefer this tool when the user asks for a holistic view, rather than chaining separate single-source lookups. It does not explicitly discuss when to prefer sibling tools like compare_entities or resolve_entity, but the main usage rule is clear enough for most routing decisions.

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

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

Description confirms deletion, aligning with destructiveHint=true annotation. However, it adds no extra behavioral context beyond what annotations already declare.

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

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

Two sentences, front-loaded with purpose, no extraneous information.

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

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

For a simple one-parameter tool with clear annotations, the description is complete: explains purpose, usage context, and relationship to siblings.

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

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

Schema coverage is 100%, so the schema already documents the key parameter. Description does not add additional meaning beyond the schema.

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

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

Description clearly states the tool deletes a stored memory by key, specifying verb, resource, and identifier. It distinguishes from siblings remember and recall.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with remember and recall.

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 convey read-only, idempotent, non-destructive behavior. The description adds process details: fetches the page, extracts title/description/key links, and emits standard markdown. This provides useful context beyond annotations, though rate limits or failure modes are not mentioned.

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

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

The description is two sentences plus a bulleted list of use cases, efficiently front-loading the purpose and output format. Every sentence adds value with 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?

Despite lacking an output schema, the description explains the output format ('single text blob ready to drop at site-root/llms.txt') and the process (fetch, extract, emit). For a straightforward tool, this is sufficiently 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?

Input schema covers 100% of parameters with clear descriptions (url examples, max_links defaults and limits). The tool's description does not add new information about parameters, maintaining the baseline of 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and purpose (AI crawler indexing). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than 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?

The description lists specific use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly state when not to use or name alternative tools. However, the context is clear enough for an agent to decide.

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 adds some value by listing the returned fields but does not provide additional behavioral context beyond what is already in annotations. No contradiction.

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

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

Two sentences, no wasted words. First sentence states purpose and output, second gives usage guidance. Efficiently structured.

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

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

For a simple tool with one optional boolean param and no output schema, the description is complete. It covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% and the description does not add extra meaning to the 'include_inactive' parameter beyond what the schema provides (boolean, default false). 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 'List the caller's active subscriptions' and enumerates the returned fields (id, type, params, etc.). It distinguishes itself 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context but does not explicitly state when not to use it.

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

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

Annotations are all false and convey no behavioral nuance, so the description carries the full burden. It discloses key behaviors: returning a claim_token when filing without an account, how to later use that token to read the resolution, the rate limit of 5 per identifier per day, and that it's free and doesn't count against quota. This goes well 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 long but every sentence earns its place. It front-loads the purpose, then logically flows through when-to-use, exclusions, message guidelines, token mechanics, rate limits, and cost. The structure is coherent and the density is appropriate for a tool with this many nuances and constraints.

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

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

Given the tool's complexity (multiple feedback types, scope restrictions, claim_token flow, rate limiting) and the lack of an output schema, the description covers all essential aspects an agent needs to invoke it correctly. It explains what the tool returns (claim_token) and the follow-up use case, making it complete even without an output schema.

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

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

The schema already has 100% coverage with detailed property descriptions. The description nevertheless adds extra meaning: it explains how claim_token works (returned from prior filing, pass it alone to read status) and provides guidance on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This exceeds the baseline for high schema coverage, though slightly less comprehensive than a full per-parameter breakdown.

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

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

The description opens with a clear, specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates the exact types of feedback (bug, feature/data_gap, praise) and explicitly scopes it to Pipeworx tools, distinguishing it from sibling tools like ask_pipeworx which are for asking questions rather than submitting feedback.

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 criteria for each feedback category and a strong when-not-to-use clause: 'ONLY for tools served by this Pipeworx connection' with a clear alternative to file elsewhere. It also instructs on how to reference Pipeworx tools/packs and avoid pasting user prompts, giving agents actionable context for invoking the tool appropriately.

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 true. Description adds valuable behavioral context: data source (CF analytics-engine), no PII, cached 5min-1h, and output structure (pack, tool, count). No contradictions.

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

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

Concise yet informative. Front-loaded with output, then use cases, then technical details. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully explains return contents (top tools, packs, total call volume) and data provenance. Complete for a simple trending tool with one optional parameter.

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 the single parameter. Description adds practical guidance on choosing window length ('hot right now' vs 'steady-state demand'), enhancing the enum 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 returns top tools, top packs, and total call volume over recent windows. It distinguishes from siblings by focusing on what other AI agents are calling, with concrete use cases.

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

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

Three explicit use cases are given (discovering hot data sources, confirming canonical tools, aligning use cases). The window parameter guidance is provided (short vs long windows). Lacks explicit 'when not to use' but context from sibling tools makes it 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?

Description goes well beyond annotations (which already indicate read-only/idempotent) by detailing arbitrage detection logic, partition checks, semantic anchor, fill check, and realizable edge conditions. 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?

Front-loaded with purpose, then organized by mode with clear headings. Each section adds necessary detail without redundancy. Length is justified by complexity.

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

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

Despite no output schema, the response structure is fully described (opportunities[], partition_check with fields, fill check indicators). All key behaviors are covered, including filters and trade recommendations.

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

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

Both parameters have schema descriptions. The description adds significant value: examples of event slugs and topic queries, explains mode behaviors, and handles edge cases like full URLs accepted.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and explains each, making it distinct from siblings like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance is provided: recommend event for specific markets, topic for cross-event scanning; contrasts cross-event vs single-event. Notes when not to trade (realizable_edge_pp ≤ 0) and references polymorphic_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds substantial behavioral context: caching behavior (1h at KV level), diagnostic feedback for empty segments, and detailed model logic. This exceeds what annotations provide.

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

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

The description is very long and detailed, which is justified by complexity, but some sentences are verbose and could be streamlined. For example, the model details and diagnostics explanation could be shortened. It is well-structured with sections, but conciseness is sacrificed.

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 (9 parameters, no output schema), the description is remarkably complete. It covers response structure (segments), edge cases (Fed markets, empty segments), and tradeable-edge filters. No gaps in explanation.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond schema definitions, such as explaining that edge is net of slippage, partition arbs return kelly_fraction_half=0, and min_partition_leg_kelly suppresses thin partitions. This enriches parameter understanding.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies three model families and the use case 'what should I bet on today'. This provides a specific verb and resource, distinguishing it from siblings.

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

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

The description explains the tool is built for discovery without paging hundreds of markets and provides knobs to filter tradeable edges. However, it does not explicitly contrast with related tools like polymarket_arbitrage or polymarket_edge_tracker, nor specify 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?

The description provides extensive behavioral details beyond the annotations (readOnly, openWorld, idempotent, non-destructive). It explains response structure (tracked[], expired[], snapshot_dates[]), limits (60-day TTL, snapshot gaps), and that decay is from daily closes, not intraday. 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 well-structured, front-loading the core purpose. While it is relatively detailed and technical, every sentence adds necessary information. It could be slightly more concise but remains clear.

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

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

Despite lacking an output schema, the description fully explains the return fields and their meanings, including edge_pp_net time-series, trend, decay rate, and snapshot_dates. It also covers limits like history depth and TTL, making it complete for an agent.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description repeats the defaults and adds some context (e.g., 'snapshot family' for window), but does not significantly enhance meaning beyond the schema.

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

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

The description explicitly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself by focusing on edge duration, which is distinct from sibling tools like polymarket_edges.

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

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

The description gives clear context on when to use the tool, e.g., when needing edge persistence information. It notes the limitation that decay numbers are from daily closes, not intraday, implying when not to use it. However, it does not explicitly list alternative tools for other use cases.

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 (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false) already indicate a safe read operation. The description adds significant context: it requires either 'market' or 'event', details the returned fields including risk-related ones like 'thin_legs' and 'forced_directional_risk', and warns about stranded positions. 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 relatively long but well-structured: a one-sentence purpose, a requirement statement, then separate sections for single-market and basket modes with bullet-like lists of return fields. Every sentence adds information, and the warnings are included. It could be slightly more concise, but the structure is clear.

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

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

The tool has no output schema, so the description must describe return values adequately. It does so comprehensively for both modes, listing all return fields (top_of_book, vwap_fill_price, slippage_pp, etc. for single-market; theoretical_sum, capture_ratio, profit_usd, etc. for basket). It also covers edge cases (thin_legs, forced_directional_risk). For a tool with 4 parameters and significant complexity, this is 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 the baseline is 3. The description adds value beyond the schema by explaining defaults (size_usd default 1000, clamp 10-1M), auto side selection for basket, and the distinction between single-market 'size_usd' interpretation (spend vs proceeds) and basket 'settlement notional'. This is useful context beyond parameter names and types.

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 begins with a specific verb-resource pair ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and immediately distinguishes between single-market and basket modes. It clearly states what the tool does and differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains the consequence of not using it: partial basket fills convert an arb into an unhedged directional position, which is the dominant loss mode. This provides clear usage 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?

Beyond the read-only/idempotent annotations, the description discloses non-obvious matching behavior: unknown metric_type or match_subtype legs are never paired, temporal_alignment null means 'could not compute' rather than aligned, and Kalshi fees are not modeled (spreads are gross). It also lists machine-readable compatibility codes and their meanings, which no structured field provides.

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 it is organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loads the core purpose. Some concepts are repeated for emphasis (e.g., 'in EITHER mode') and the enumeration is dense, so it is not maximally concise, but no section feels gratuitous given there is no output schema.

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

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

For a 3-parameter tool with no output schema, the description documents the return shape (prices, top_spreads_pp, compatibility_warning/codes, temporal_alignment, fees_note, skipped counters), explains null semantics, flags pitfalls, and specifies what is excluded. An agent has enough to call and interpret the result safely.

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

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

Schema coverage is 100%, and the description adds mode-level semantics: topic is an auto-fetch shortcut, explicit kalshi_event_ticker/polymarket_event_slug form a custom pairing, and both modes run the same token-overlap matcher with the same safety fields. It doesn't restate syntax because the schema already does, but it supplements with behavioral meaning.

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

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

The description opens with a specific verb/resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It goes on to define the matching criteria and the return value (Kalshi − Polymarket in pp), so an agent can distinguish it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

It gives clear usage context with TWO MODES — 'topic' shortcuts vs explicit ticker/slug — and warns that pre-mapped topics are not automatically tradeable and that real spreads are rarer than the macro-shortcut list suggests. It stops short of nominating sibling alternatives for cases where this tool is a poor fit, so it gets 4 rather than 5.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds context about scoping (anonymous IP, key hash, account ID) and pairing with other tools, which is useful 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 well-structured sentences, front-loaded with the main action. No wasted words, each sentence contributes meaning.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: explains behavior, scoping, and pairing with siblings.

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 for the key parameter. The description reiterates the behavior ('omit to list all keys') and adds clarity about the key's purpose, providing extra value beyond the schema.

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

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

The description clearly states the tool retrieves values saved via remember or lists all keys when no key is provided. It distinguishes from sibling tools like remember (save) and forget (delete).

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

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

Explicitly says when to use: to look up context stored earlier, avoiding re-derivation. Contrasts with alternatives and mentions pairing with remember and forget.

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 readOnly, idempotent, and non-destructive. The description adds valuable behavioral details: mark_read effect on future calls, and that polling works fine. No contradictions; description enriches understanding beyond annotations.

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

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

Four sentences, front-loaded with core action, no redundancy. Every sentence adds value: returns fields, filter options, mark_read behavior, alternative access.

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, description adequately mentions return fields (source, citation_uri, payload). All input parameters are covered by schema. Minor gap: behavior of unread_only could be mentioned, but schema covers it. Contextually complete for a retrieval 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 has 100% description coverage, so baseline is 3. Description reiterates filter by type and since, and explains mark_read's effect, but does not add meaning for limit or unread_only beyond schema. Adequate but not exceptional.

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 fired events from a subscription feed, specifying the returned fields (source, citation_uri, payload). The verb 'Pull' and resource 'fired events' are specific, and the tool is distinct from sibling tools like list_subscriptions or subscribe.

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 mentions polling works fine and points to an alternative REST endpoint for scripts/dashboards, providing context for when to use the tool programmatically. However, it does not explicitly state when to choose this tool over sibling tools like recent_changes.

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 adds value by detailing multi-source fan-out, rate-limiting fallbacks, and output structure (changes[], total_changes, citation URIs). No contradictions.

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

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

Well-structured and front-loaded with purpose. Efficiently packed with information in a single paragraph. Could benefit from slight structural separation (e.g., parameters), but overall concise.

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

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

Given the tool's complexity (multiple sources, fallbacks, soft-failure) and absence of an output schema, the description covers essential behavioral details and output format. Limitations (USPTO) and alternatives (entity_profile) are noted.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches with examples (ISO date, relative shorthand like '30d', ticker vs CIK) and usage notes (typical monitoring window). Adds meaningful context 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 the tool's purpose: fetching recent changes (SEC filings, news, patents) for a company in a time window. It gives example queries and explicitly distinguishes from sibling tool 'entity_profile', making the purpose unambiguous.

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

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

Excellent usage guidance: example queries, fallback behavior (GDELT preferred, GNews on rate limit/5xx), soft-fail for USPTO until May 2025, and clear directive to use 'entity_profile' for static profiles regardless of window.

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 context beyond annotations: persistence duration (24h anonymous), scope by identifier, and intended use as storage. No contradictions with annotations (idempotentHint true, destructiveHint false).

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

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

Four sentences, front-loaded with purpose, each sentence adds unique value. No redundant or filler content.

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

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

No output schema, but description fully covers purpose, usage, behavioral details, and parameter guidance. Complete for a storage tool with simple key-value semantics.

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 has 100% coverage with descriptions. Description adds value by providing example keys and values (e.g., 'subject_property', 'target_ticker'), enhancing semantics beyond schema alone.

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

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

Description uses specific verb 'Save data' and resource 'key-value pair' with concrete examples (resolved ticker, target address). Clearly distinguishes from siblings 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 states when to use ('when you discover something worth carrying forward') and pairs with recall and forget. Mentions scoping and persistence differences between authenticated and anonymous sessions.

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, and the description adds substantial behavioral context: ambiguous matches return figi_candidates instead of asserting, identifiers are source-labelled, unresolved identifiers are listed, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. This goes far beyond annotation coverage and is highly relevant to calling the tool correctly.

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 trigger examples and the direct 'Use FIRST' instruction, but it is a long, dense block with a massive parenthetical and multiple clauses. Most sentences carry unique information, so nothing is fluff, but the readability suffers from the run-on structure. It earns credit for density but loses a point for lack of conciseness.

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

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

There is no output schema, so the description carries the burden of explaining return content. It does so thoroughly: for companies it lists the delivered identifiers (CIK, ticker, company_name, LEI, FIGI, ownership), and for drugs it lists RxCUI, ingredient, brand, and citation. It also covers failure modes (ambiguity, source unavailability, unresolved identifiers), making the behavior fully comprehensible to an agent.

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

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

Schema description coverage is 100%, so the baseline is 3, but the tool description enriches both parameters. The 'type' parameter gains meaning through detailed explanations of what a company lookup returns versus a drug lookup. The 'value' parameter is augmented with input formats (ticker, CIK, ISIN, brand/generic name) and the critical caveat about passing the entity name only, not the full noun phrase. This surpasses the schema's brief 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: 'resolve a user-spoken NAME to the canonical/official identifiers.' It opens with concrete trigger examples and positions itself as the 'FIRST' step when a name is present but an ID is needed, clearly distinguishing it from downstream tools like entity_profile or direct RxNorm lookups. The scope (names to identifiers, including CIK, LEI, FIGI, RxCUI) is explicit 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use rule. It enumerates supported types and accepted input formats. However, it does not name an alternative tool for when not to use it (e.g., if the agent already has an ID), so it stops short of the full when/when-not/alternatives structure.

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 safety characteristics (readOnlyHint, idempotentHint, non-destructive), so the description does not need to repeat them. The description adds workflow and return-field context, but does not disclose any distinctive behavioral traits beyond what annotations and the schema provide.

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

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

The description is three short sentences with the action, return fields, and workflow context front-loaded. The only minor issue is redundancy between 'full medication details' and 'complete drug information,' which prevents a perfect score.

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

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

For a single-parameter, read-only tool with an output schema and strong annotations, the description is nearly complete: it names the expected input type, highlights return fields, and links to the correct preceding tool. The main gap is lack of explicit sibling exclusions, but this is not critical given the simple scope.

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

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

Schema coverage is 100%, and the parameter description already explains that rxcui accepts either an RxCUI ID or a drug name that is resolved automatically. The tool description only repeats 'by RxCUI ID' and actually understates the name-resolution behavior, so it adds no extra semantic value here.

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 ('Get full medication details by RxCUI ID') and lists concrete return fields: name, synonyms, term type, language, and status. It also names rxnorm_search as the preceding workflow step, which helps distinguish this property-lookup tool from the search sibling.

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

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

The description explicitly says 'Use after rxnorm_search to retrieve complete drug information,' which gives clear workflow context for when this tool should be called. It does not explicitly say when not to use rxnorm_related or rxnorm_ndc, so it stops short of full when-not/alternative guidance.

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

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

The description adds valuable behavioral context beyond the annotations: it explains that NDCs attach to marketed products, that ingredient names are automatically expanded to products, and that the response explicitly indicates such expansion. It also discloses the historical NDC count behavior for non-marketed concepts, which prevents confusing empty responses. This goes well beyond the readOnly/idempotent hints.

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

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

The description is three sentences, front-loaded with the main purpose, then provides essential behavioral details. Every sentence adds value: purpose, input flexibility, and edge-case behavior. No redundant or filler content.

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 a full input schema, output schema, and annotations (readOnly, openWorld, idempotent), the description covers all necessary context: input types, automatic expansion, and historical count behavior. It is complete for a single-parameter lookup tool, anticipating likely user confusions.

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 describes the 'rxcui' parameter thoroughly, including that it can accept an RxCUI or drug name and how ingredient expansion works. Since schema_description_coverage is 100%, the description adds little new parameter-level meaning; it mostly reinforces what the schema already says. A baseline of 3 is appropriate.

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

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

The description opens with 'Get the NDC (National Drug Code) identifiers for a drug', a specific verb+resource combination that clearly states the tool's function. It distinguishes itself from sibling tools like rxnorm_search and rxnorm_get_properties by focusing exclusively on NDC identifiers, making its purpose unmistakable.

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

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

The description provides clear context on when to use this tool (when NDC codes are needed) and what inputs are acceptable (RxCUI or plain drug name). However, it does not explicitly mention alternatives or exclusions, such as recommending rxnorm_search for general search or rxnorm_get_properties for other drug properties. The guidance is clear but not exhaustive.

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

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

Annotations already establish the operation as read-only, idempotent, open-world, and non-destructive, so the description only needs to add behavioral context. It explains what the tool returns—related medications across brand, generic, ingredient, and dose-form categories—and describes the brand/generic mapping behavior. No contradiction with annotations exists.

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

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

The description is compact and front-loads the core behavior, with only a short usage directive at the end. The final sentence is somewhat generic, but it does not add meaningful waste, so the structure remains 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 is sufficient for a read-oriented relationship lookup tool when combined with a fully covered input schema, rich annotations, and an output schema. It conveys the relationship categories and intended use while leaving parameter formatting details to the schema, which already handles them thoroughly.

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 coverage is 100%, and the schema already documents rxcui (including drug-name resolution) and the tty filter with accepted values, separators, case-insensitivity, and defaults. The description's reference to brands, generics, ingredients, and dose forms aligns with tty values but adds no parameter details beyond the schema.

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

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

The description states a specific action ('Find related medications by RxCUI') and enumerates the relationship categories returned: brands, generics, ingredients, and dose forms. It is clear and scoped, but it does not explicitly differentiate itself from sibling tools like rxnorm_search or rxnorm_get_properties.

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 direct use case: 'Use to compare drug options,' and the mapping sentence supports the brand-to-generic alternative scenario. It does not state when not to use the tool or mention a preferred alternative, so it stops short of full usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. The description adds valuable context beyond annotations by detailing return values (RxCUI, names, synonyms, term types) and explaining term type abbreviations (BN, IN, SBD). It does not contradict annotations. While it could mention behavior when no match is found, the provided context is strong.

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

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

The description is two sentences long, front-loading the primary purpose and then expanding with examples and return types. Every sentence is substantive and earns its place. No redundancy or filler.

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

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

Given the tool's simplicity (1 required param, full schema coverage, output schema, and annotations indicating safe read), the description is complete. It explains what the tool does, what it returns, and positions it as the entry point for RxNorm queries. No gaps remain for effective use.

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 single parameter 'name' is fully described in the schema (100% coverage) with examples. The description reiterates 'Search by brand or generic name' and gives examples, but adds no meaning beyond what the schema already provides. Baseline is 3 due to full schema coverage.

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

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

The description clearly states the tool's purpose: look up a medication's RxCUI and map brand to generic (and vice versa). It provides concrete examples (Eliquis->apixaban, Lipitor->atorvastatin) and specifies the returned data: RxCUI IDs, names, synonyms, term types. This distinguishes it from siblings like rxnorm_get_properties by framing it as the starting point for finding a drug's unique ID.

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

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

The description explicitly lists use cases: 'what is the RxCUI for X', 'what generic ingredient does brand X map to', 'brand vs generic name'. It advises 'Start here to find a drug's unique ID', giving clear context. However, it does not mention when NOT to use it or contrast with siblings like rxnorm_ndc or rxnorm_related, missing an opportunity for explicit exclusions.

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

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

The description details internal behavior: probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It adds context beyond the annotations (readOnly, idempotent, etc.), such as the return structure (ranked list with score, confidence, signal density). No contradictions.

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

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

The description is two sentences plus a literal example, front-loaded with purpose. Every sentence adds value, with no fluff 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?

Given the tool has 4 parameters and no output schema, the description adequately covers return value (ranked list with score, confidence, signal density) and internal logic (probing with ai_visibility_check). It is complete for the complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond the schema's own parameter descriptions (e.g., entities, context, models). It repeats the purpose but provides no additional syntax or constraints.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly states the use case ('competitive AI-marketing audits') and provides a concrete question example. It implies when to use (side-by-side comparison) but does not explicitly exclude single-entity checks or mention alternatives, though sibling tools imply them.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: external APIs are called (deps.dev, bundlephobia), bundlephobia's first measurement can take 5-30s and may time out with sources_failed, and the return format includes summary, advisories, links, and alternative versions. 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 a single paragraph that front-loads the core purpose. It is informative but slightly lengthy due to comprehensive detail. Every sentence serves a purpose, but could be trimmed marginally. Still well-structured and efficient.

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

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

Given the complexity (multiple data sources, partial failure, no output schema), the description covers return value structure (summary block fields, per-advisory, links, alternative versions), limitations (NPM only, bundlephobia latency), and graceful degradation. Fully adequate for an agent to understand behavior.

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

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

Schema coverage is 100% with clear descriptions for 'package' (npm package name, scoped accepted) and 'version' (optional, defaults to latest). The description mentions defaulting to latest but adds little beyond schema. Baseline 3 is appropriate; no extra semantic richness.

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

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

The description starts with a specific verb-resource combination ('Composite check ... in ONE call') and clearly states the tool scans npm packages for safety, popularity, size, etc. It distinguishes from other tools by explicitly noting NPM-only scope and referencing sibling tools for other ecosystems (deps.dev:version directly).

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

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

The description explicitly states when to use: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. It also provides exclusions ('NPM ecosystem only in v1') and alternatives ('PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), plus behavior under partial failures.

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 technical details: BGE-base-en embeddings, cosine similarity over 500-char windows, 200K char cap with truncation flag, and output format (offsets, scores). 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 with front-loaded purpose. Each sentence serves a distinct function: purpose, usage guidance, technical details. No redundant 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?

Covers input constraints, output format (passages with offsets and scores), technical parameters (embeddings, window size, char cap), and usage scenario. No missing information for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline 3. Description adds value beyond schema: provides examples for query, specifies default and range for limit (1-20, default 5), and clarifies that text is the document to search (max 200K chars).

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 'Semantic search INSIDE a fetched record', specifies the verb (search), resource (record text), and distinguishes from sibling ask_pipeworx_grounded. It also explains when to use it (when record is too large for prompt).

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

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

Provides explicit when-to-use guidance: 'Use when the record is too big to cram into the prompt'. Mentions pairing with ask_pipeworx_grounded as an alternative. Lacks explicit when-not-to-use but context is clear.

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

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

Beyond annotations (non-read-only, idempotent, non-destructive), the description details behavioral traits: returns a new subscription ID, explains delivery channels (feed always on, optional email/sms/webhook), caps on SMS (10/day), webhook auto-disable after 10 failures, and HMAC signing. This provides comprehensive behavioral context.

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

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

The description is thorough and structured with bullet points and examples, but it is somewhat lengthy. Every sentence adds value, but it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (multiple subscription types, optional delivery channels, and no output schema), the description fully covers required fields, parameter structures, delivery options, limitations, and prerequisites. It leaves no obvious gaps for an agent to operate 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%, but the description adds significant meaning: it explains each subscription type's parameters with concrete examples (e.g., sec_8k: items, polymarket_edge: topic/min_spread_bps), delivery channel fields with validation rules (E.164, HTTPS only, email pattern), and webhook signing details. This goes far beyond the schema.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream.' It also distinguishes it from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation and persistence.

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

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

The description specifies prerequisites (Pipeworx OAuth account), explains when to use each subscription type with examples, and notes limitations (e.g., anonymous/BYO cannot persist). It does not explicitly state when not to use, but the detailed guidance covers common scenarios.

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 adds context about returning categorized examples and the effect of omitting the topic parameter, enhancing transparency without contradiction.

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

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

The description is fairly long but each part adds value: synonyms for user queries, explanation of output, topic examples, and usage guidance. Slightly verbose but efficiently structured for an agent.

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

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

For a tool with 1 optional parameter and no output schema, the description fully explains when to use it, what it returns, and how to call it, making it self-sufficient for an agent.

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

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

Schema provides 100% coverage for the only parameter (topic), and the description adds more detail: lists allowed values (finance, pharma, etc.) and explains behavior when omitted, adding significant meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions with tool+argument shapes, listing specific use cases like 'what can I ask?' It distinguishes from siblings by being the onboarding entry point.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains the optional topic parameter, providing clear context for when to use versus other tools.

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

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

The description adds significant behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and the impact on historical events via recent_alerts. Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are consistent and enriched by this explanation.

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, no wasted words. First sentence states the core action, second adds critical constraints. Information is front-loaded and efficiently presented.

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

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

For a single-parameter tool with no output schema, the description covers purpose, ownership, side effects (deactivation vs deletion), and linkage to recent_alerts. It is adequately complete for an agent to use correctly.

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

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

Schema coverage is 100%, and the description adds meaning by stating that the id is 'returned by subscribe', connecting the parameter to the workflow context. This adds value beyond the schema definition.

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

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

The description clearly states the action: 'Cancel a subscription by id.' It also explains ownership enforcement and the deactivation behavior, distinguishing it from sibling tools like subscribe, list_subscriptions, and recent_alerts.

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 want to cancel a subscription you own. It mentions ownership enforcement and the effect on historical events, providing context but not explicitly excluding alternatives or giving when-not-to-use guidance.

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

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

Despite readOnly/idempotent annotations, the description adds substantial behavioral context: internal pipeline routing, verdict taxonomy, and the critical nuance that 'could_not_verify' is not evidence for/against a claim. Warns about verification_error{stage,detail} and 'unsupported' semantics. 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?

Approximately 180 words, front-loaded with purpose and usage. Content-dense with useful bullets and emphasis. While longer than a two-sentence ideal, the complexity of the tool (two paths, multiple verdicts, edge-case warnings) justifies the length.

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

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

No output schema exists, yet the description explains the return value (verdict, actual value, citation, reasoning) and clarifies ambiguous states ('could_not_verify' vs 'unsupported'). It also covers both claim-type handling and the efficiency advantage, fully equipping an agent to use the tool.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description adds trigger phrases and an example for 'claim', and mentions 'exact percent-delta math' and 'tolerance' for 'tolerance_pct', but these largely echo the schema descriptions rather than introducing new meaning.

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 verb+resource: 'natural-language claim verification against authoritative sources.' Lists multiple trigger phrases ('fact check', 'verify the claim that') and explicitly distinguishes it via the verdict-output and replacement of sequential calls. Strongly differentiated from sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Also differentiates company-financial vs other claims. However, it does not name alternative tools or state when NOT to use it (e.g., for open-ended research), so lateral guidance is incomplete.

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