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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description reinforces these by describing a read-only, non-destructive question-answering tool. It adds behavioral context beyond annotations: 'returns the structured answer with stable pipeworx:// citation URIs,' 'works on every tier,' and 'one fast call.' However, it does not disclose potential failure modes, latency variations, or what happens when the question is out of scope, so a 4 is appropriate rather than 5.

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 and front-loaded: it opens with 'PREFER OVER WEB SEARCH,' lists concrete data types and examples, then provides usage guidance and alternatives. Every sentence carries meaningful information—types of queries, examples, tier availability, and upgrade paths—without redundancy or irrelevant detail. The length is justified by the tool's complexity.

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

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

Given the tool's breadth (5,635 tools across 1477 sources) and lack of output schema, the description is exceptionally complete. It covers when to use the tool, when to step up to alternatives, the return format (structured answer with citation URIs), and even addresses breaking news routing. It also mentions the tool works on all tiers and provides concrete examples, leaving no major gaps for an agent to call it correctly.

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

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

Schema description coverage is 100%, with all 6 parameters documented (question and its aliases). The description adds only that the question is 'natural language,' which is already implied by the schema's description and examples. No additional parameter semantics are provided beyond what the schema already covers, so the baseline of 3 applies.

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

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

The description clearly states the tool answers factual questions about real-world data with citations, routes to one of 5,635 tools, and returns structured answers. It distinguishes itself from siblings by positioning as the 'default entry point' and explicitly naming alternatives like ask_pipeworx_grounded and deep_research, making its role 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 instructs to 'PREFER OVER WEB SEARCH' for a broad list of data types, gives concrete query examples, and states 'Use whenever the user asks...' for factual questions. It also specifies when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'), providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds valuable context: it's a beta with candidate routing improvements, currently matching stable after the last candidate was retired, and it's a full working router. This goes beyond annotations by explaining the experimental nature and the comparison pipeline, which is essential for an agent to set expectations.

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, front-loading the beta identity and core functionality, then explaining the current state, usage, and reassurance of full capability. Each sentence contributes meaning without redundancy, making it concise for the complexity involved.

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 multi-tool router, the description covers the essential operational context: beta status, current parity with stable, usage as a full router, and the comparison mechanism. It points to ask_pipeworx for parameter and response details, which is sufficient given the explicit reference. Lacking a direct note on response format is minor since it says 'same response shape' as stable.

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 provides 100% coverage with descriptions for all six parameters, including aliases for the 'question' parameter. The description adds no parameter-specific details, so it neither improves nor degrades beyond what the schema already conveys. 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 explicitly identifies the tool as a beta version of ask_pipeworx, a universal router over 5,635 tools with the same arguments and response shape as the stable version. It distinguishes itself from the stable ask_pipeworx and mentions the experimental edge, 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 gives direct guidance: 'Use it exactly like ask_pipeworx when you want the newest routing', and explains the results are compared against the stable router. This names the when-to-use condition and the alternative (stable ask_pipeworx), leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral traits beyond that: it discloses an extra LLM call cost, the refusal logic with specific refusal reasons, and the guarantee that answers are extracted ONLY from tool results. This gives the agent critical behavioral context that annotations alone cannot convey.

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

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

The description is dense but every sentence earns its place: it states the purpose, explains the mechanism, lists the return/refusal format, gives explicit usage scenarios, and mentions the cost vs. alternative. It is front-loaded with the core purpose and then provides necessary detail without redundancy. Structured with clear segmentation, it remains easy to scan.

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

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

Given there is no output schema, the description compensates fully by specifying the exact return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}) and the refusal reasons. It also covers the extra call cost and the alternative tool. For a complex grounded-answer tool, this is complete; an agent has everything needed to decide when and how to use it.

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

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

The schema already documents the question parameter and all aliases with a 'description' covering each alias, achieving 100% schema coverage. The description does not add any new semantic detail about the parameter beyond saying it is natural language, which is already in the schema. Per the baseline rule for high coverage, 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 a specific purpose: a 'hallucination-resistant answer mode for high-stakes reads.' It clearly states what it does (routes, fetches, extracts using only tool results) and distinguishes itself from ask_pipeworx by the grounding and refusal mechanism. This is a clear, specific verb+resource definition that sets it apart 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?

Provides explicit when-to-use criteria: 'Use whenever an answer will be quoted, cited, or acted on...' and names concrete exclusions (financial verdicts, legal claims, medical lookups, public statements). It also states the trade-off ('costs one extra LLM call') and directs users to prefer ask_pipeworx for casual lookups, explicitly naming the alternative.

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial context: account/payment requirements, expected latency (15-60s, up to ~90s for thorough), the findings packet elements (evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, citation_uri conditions), and semantic excerpting behavior. No contradiction with annotations.

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

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

The description is long but densely informative, front-loading the critical account requirement and alternative tool before diving into mechanics. Each sentence adds operational value, though it could be trimmed without losing essential information. It is structured logically but still verbose.

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

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

For a tool with no output schema, the description fully describes the return packet: findings with evidence, confidence, source, timestamps, stable citations, gaps, contradictions, hop field, and citation_uri conditions. It also covers edge cases (large-record excerpting, latency expectations) and account tiers. Nothing an agent needs to use the tool correctly is missing.

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

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

Schema coverage is 100% and the schema's depth parameter already describes quick/standard/thorough with their hop and contradiction differences. The description mostly reiterates this, adding only latency expectations and minor clarifications about gap recovery. It provides marginal value above the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1477 STRUCTURED data sources' and decomposes questions into facets routed to 5,635 tools in parallel. It explicitly distinguishes itself from open-web search and its sibling ask_pipeworx, making its unique role 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?

Exceptional guidance: it states it's 'Best for broad/multi-part questions over structured data', explicitly says 'For a single lookup use ask_pipeworx', and warns that for BREAKING/current-news topics to prefer ask_pipeworx. It also conditions usage on account tier ('if you are not signed in, use ask_pipeworx'). No ambiguity about when to use this tool.

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

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

Annotations already 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description details data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), return fields with examples, and limitations (patents soft-fail until May 2025, names not supported). This fully discloses behavior and edge cases.

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 example queries and the main purpose, followed by detailed return structure and limitations. While verbose, each sentence adds value. Could be slightly more concise, but overall efficient for the 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?

Given no output schema, the description fully explains return values (cik, filings, fundamentals, patents, news, LEI) with specifics like 'LATEST 10-K Revenues + NetIncomeLoss + Cash, sorted period_end DESC' and fallback behavior. Combined with annotations, it provides a complete understanding of the tool's behavior and 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?

Schema coverage is 100% and schema descriptions already explain parameter constraints (type only 'company', value as ticker or CIK, names not supported). The tool description reinforces these points but adds no new parameters or semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description explicitly states the tool provides a holistic cross-source profile of US public companies, with specific example queries like 'tell me about X' and 'research Acme'. It clearly differentiates from single-pack lookups by noting it fans out across multiple sources in one parallel call.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and warns that names are not supported, directing to use resolve_entity first. This gives clear when-to-use and 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?

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?

The description adds substantial behavioral context beyond annotations (readOnlyHint, idempotentHint). It details compatibility_warning conditions (non-equivalent bet shapes, no token overlap), temporal_alignment constraints, and skipped_cross_type/cross_subtype counters, giving a comprehensive picture of tool behavior and edge cases.

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

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

The description is long but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core concept. Every sentence adds useful information, though a minor trim could improve 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?

Despite lacking an output schema, the description thoroughly explains the response fields (spread, compatibility_warning, temporal_alignment, skipped counters) and covers critical safety fields that are essential for correct agent invocation. This provides complete contextual understanding for a tool with complex safety logic.

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

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

With 100% schema description coverage, baseline is 3. The description adds value by listing the 10 topic shortcut values, explaining that explicit tickers override topic, and clarifying the auto-fetch behavior. This enriches understanding beyond the schema's basic string descriptions.

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

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

The description clearly states the tool's purpose: cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage (which focuses on intra-venue arbitrage) by specifying cross-venue functionality and leveraging venue differences.

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

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

The description provides explicit guidance on two modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics return compatibility_warning today, indicating they may not be immediately tradeable. However, it does not explicitly contrast this tool with alternatives like polymarket_arbitrage, though the context of cross-venue spread is clear.

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

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

Annotations already 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses graceful degradation when external sources (GLEIF, OpenFIGI) are unavailable, and that unresolved identifiers are explicitly stated. It also mentions internal cascading lookups, adding significant behavioral context that annotations alone do not provide.

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

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

The description is well-structured with engaging examples up front, clear guidelines, and detailed type explanations. While it is lengthy, every sentence adds value; however, minor redundancy (e.g., repeating 'canonical/official' in multiple forms) prevents a perfect conciseness 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?

Despite lacking an output schema, the description thoroughly explains the return structure, including which identifiers are provided, how they are labelled, and what happens when resolution fails. It covers both entity types comprehensively and addresses edge cases like degradation, 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?

The description adds substantial meaning beyond the schema: for 'company', it explains that input can be ticker, CIK, ISIN, or name, and details the resolved identifiers (CIK, LEI, FIGI). For 'drug', it specifies RxCUI, ingredient, brand. This enriches the schema's simple enum and string descriptions considerably.

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

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

The description clearly states that the tool resolves a user-spoken name to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID', making its primary role 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 recommends using this tool first when needing an ID from a name, and details the supported entity types (company, drug) with clear input formats. It also implies when not to use it (when you already have an ID) and contrasts with manual alternatives, providing strong 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description does not need to repeat these. It adds no further behavioral traits beyond stating that it returns medication details. With strong annotations, baseline transparency is adequate.

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

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

The description is two concise sentences, front-loaded with the action and result, and includes a usage hint. No extraneous words 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 annotations, full schema coverage, and presence of an output schema, the description is largely complete. It provides the essential flow (after rxnorm_search) and mentions returned fields. Minor gaps (e.g., no error handling mention) but overall sufficient for a simple read 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?

The input schema has one parameter (rxcui) with 100% description coverage, including an explanation that it accepts either an RxCUI or drug name. The tool description does not add additional parameter meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Get full medication details by RxCUI ID' and specifies the returned fields (name, synonyms, term type, language, status). It also distinguishes from sibling tools by referencing rxnorm_search as a prerequisite.

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

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

The description provides explicit usage context: 'Use after rxnorm_search to retrieve complete drug information.' It indicates when to use the tool but does not list alternatives or when not to use it, though the flow 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?

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds behavioral context about 'mapping between brand and generic alternatives' and listing types of related concepts, which is valuable beyond annotations. No contradictions.

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

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

The description is three short, front-loaded sentences with no wasted words. It states the action, includes a key capability, and ends with usage advice. Excellent 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?

Given full schema coverage, existing annotations, and an output schema, the description is mostly complete. It covers core functionality, but could mention the ability to accept drug names (as noted in the rxcui parameter description) or discuss pagination/limits. Still, it is adequate for a lookup tool.

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

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

Schema coverage is 100%, and the description adds little beyond repeating the parameter names ('by RxCUI'). While it gives overall purpose, it does not enhance understanding of individual parameters beyond the schema descriptions. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds related medications by RxCUI, listing specific types (brands, generics, ingredients, dose forms) and mentions mapping between brand and generic alternatives. This distinguishes it from sibling tools like rxnorm_search and 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 clear usage context ('Use to compare drug options') but does not explicitly exclude use cases or mention alternative tools. Given the presence of sibling tools with overlapping functionality, more explicit guidance would be helpful, but the existing context is sufficient.

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.