Nato

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

Annotations already indicate read-only and idempotent behavior. The description adds that it returns per-model data and combined view, discloses the free default model and that Anthropic calls pass through the user's API key. 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?

Three sentences, front-loaded with primary purpose, then details on models and output, then use cases. No redundant information; every sentence adds value.

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

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

For a tool with 4 parameters and no output schema, the description covers the return format per model and combined view, use cases, and model options. Could mention limitations like rate limits or that it's free tier, but overall sufficient.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by explaining default model behavior and the role of '_apiKey' in enabling Anthropic probes, enhancing understanding beyond the schema.

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

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

Clearly states the action 'probe one or more LLMs' and the resource 'business/brand/product/topic', with specific output 'score visibility (0-100) per model'. Distinguishes from sibling tools like 'compare_entities' and 'scan_competitor_ai_presence' by focusing on AI model visibility.

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

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

Provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default free model and optional Anthropic with BYO key. Lacks explicit when-not-to-use or alternatives but offers clear context for appropriate usage.

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

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

Beyond the annotations (readOnlyHint, idempotent, non-destructive), the description reveals key behavior: it routes to one of 5,529 tools across 1,455 sources, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also notes it works on every tier and makes one fast call. This adds substantial context that annotations cannot convey, and it is consistent with 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 information-dense. Every sentence adds value: the capability, the scope, the fallback chain, the examples, and operational notes (works on every tier). It is front-loaded with the most important directive. Slightly padded with marketing numbers (5,529 tools, 1455 sources), but these are useful specificity, not fluff.

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

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

For a routing tool with no output schema, the description adequately sets expectations: returns a structured answer with citations, covers even breaking news, and explains when to escalate. It also clarifies edge cases like 'what's the world saying about X' without forcing the user to try multiple tools. There is no missing information for an agent to decide to invoke 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 covers 100% of parameters, including aliases for question, so the baseline is 3. The description raises this by giving concrete example phrases and clarifying that the parameter accepts natural-language questions even when they are imperative ('5-day forecast for Tokyo'). It reinforces the schema without repeating it verbatim.

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 immediately identifies the tool as a router for factual questions, explicitly listing domains (SEC filings, FDA drug data, economic stats, etc.) and giving the action verb 'routes' and 'returns structured answer'. It distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives, so the reader knows exactly where this fits.

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

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

Usage guidance is exceptionally explicit: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and it gives trigger phrases like 'what is', 'look up', 'find'. It also provides direct alternatives with conditions: 'Step up only when needed: for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part use deep_research'. This is a model of when-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 (readOnly, openWorld, idempotent, non-destructive), the description discloses that this is a working router with no fallback wrapper, that experimental candidates may be live, and that it currently behaves identically to ask_pipeworx. It also explains the comparison process and retirement of the last candidate, providing rich behavioral context not available from annotations alone.

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

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

The description is three sentences, each adding essential value: it establishes the beta identity, clarifies the current state (no active candidate), and gives usage guidance with reassurance that it is a full router. It is front-loaded with the most important information and contains 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's complexity—a universal router with many aliases and experimental routing—the description adequately covers identity, current runtime behavior, usage conditions, and the relationship to the stable router. It also implies the response shape by referencing the same response shape as ask_pipeworx, which is sufficient 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 input schema already provides 100% coverage for all six parameters, including detailed descriptions of the `question` parameter and its five aliases. The description does not add further parameter semantics beyond saying 'same arguments' as ask_pipeworx, so a baseline score of 3 is appropriate; the description neither enhances nor contradicts 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 identifies the tool as a beta version of ask_pipeworx, specifies that it is an identical universal router with the same 5,529 tools, arguments, and response shape, and distinguishes it from the stable version by its experimental routing improvements. This goes beyond the name and title to explain exactly what the tool does and how it differs from its sibling.

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

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

The description explicitly states when to use the tool ('Use it exactly like ask_pipeworx when you want the newest routing'), provides context that results are compared against the stable router to decide merges, and notes that no candidate is currently active so it now matches ask_pipeworx. This gives clear guidance on usage and implies when to prefer the stable 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses detailed behavioral traits: it extracts answers using ONLY tool-result content, returns a structured payload with evidence and confidence, and provides an explicit refusal_reason enum (not_in_source, no_tool_match, etc.). It also mentions the operational cost of one extra LLM call, which is not captured by annotations. 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 dense but well-structured: it starts with the core purpose, then explains the internal mechanism, return payload, refusal types, use cases, and cost trade-off. Each sentence adds valuable information, though the return-format specification is somewhat lengthy. It is front-loaded with the primary purpose and remains focused.

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

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

Given there is no output schema, the description compensates by fully specifying the success and refusal return structures. It also covers routing details, tool-count/source context, use-case scenarios, and cost comparison with the sibling tool, making the description contextually complete for an agent to decide and invoke the tool correctly.

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

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

The input schema provides complete descriptions for all six parameters (including aliases) with 100% coverage, so the description does not need to add parameter-level detail. The description adds no additional meaning about the parameters, only implying that 'question' is the natural-language input. With high schema coverage, 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 clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific verb (extract) and resource (tool results from 5,529 tools across 1,455 sources). It distinguishes itself from the sibling ask_pipeworx by explicitly stating 'Same routing as ask_pipeworx' but with grounded extraction, making its unique 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?

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples (financial verdicts, legal claims, medical lookups, public statements). It also gives a clear alternative and trade-off: 'prefer ask_pipeworx for casual lookups' and notes the extra LLM call cost, offering a full when-to-use vs. when-not-to-use decision framework.

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

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

The description discloses extensive behavioral traits beyond annotations: it explains the resolution process, fan-out logic, response shapes, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, safety short-circuits, wide-spread warnings, and cancellation rule parsing. This far exceeds what annotations (readOnlyHint, openWorldHint, idempotentHint) 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 long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). It is front-loaded with the core purpose. While comprehensive, every sentence adds value; the length is justified given the tool's complexity.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is remarkably complete. It covers inputs, processing, all output fields, edge cases (low confidence, closed markets, wide spreads), safety mechanisms, and resolution rules. No important aspect is omitted.

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 covers all three parameters with descriptions (100% coverage), so baseline is 3. The tool description adds context: depth is explained as 'quick = 2-3 evidence sources, thorough = full fan-out', and include_raw explains summarized vs full payloads. Market parameter details are reinforced.

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 function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input formats (slug, URL, question text) and the output (evidence packet + market-vs-model comparison). It distinguishes itself from sibling tools by emphasizing aggregation of multiple data sources in a single 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 lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed contextual guidance, including when to inspect confidence levels and when the tool may block (low-confidence match, closed markets). This helps the agent choose between this and alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and efficiently conveys key information. While slightly lengthy, every sentence adds value, with no wasted words. A minor reduction in length could still maintain 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 (2 parameters, no output schema), the description fully covers what the tool does, its inputs, behavior, and output format (paired data + citation URIs). It is complete 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?

Schema coverage is 100% but the description adds significant meaning: it explains what each type pulls (company: specific financial metrics; drug: specific counts) and how results are sorted. This goes well beyond the schema's brief descriptions.

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

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

The description uses specific verbs ('compare', 'side-by-side comparison') and clearly identifies the resource (2-5 companies or drugs) and action. It distinguishes from siblings by explicitly stating preference over sequential single-pack lookups, which differentiates from tools like entity_profile.

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

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

The description explicitly states when to use this tool ('for comparing entities', 'ALWAYS PREFER') and provides context on entity types and data sources. It implies when not to use (for single lookups) through the sibling context and by emphasizing efficiency gains.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses account requirements, paywall for 'thorough', decomposition/routing behavior, gaps[] handling ('never invented'), citation_uri fetchability guarantees, hop field, contradictions[], semantic excerpting, and latency. This far exceeds annotation-only context.

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

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

The description is long but each section earns its place—account prerequisite, core mechanism, usage guidance, depth semantics, output details, and performance expectations. It is logically structured and front-loaded with the most critical account/alternative information, though slightly verbose.

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

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

With no output schema, the description fully describes the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field) and covers edge cases like breaking-news topics returning mostly empty gaps, plus performance expectations. This is a complete guide 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?

Although the input schema documents both parameters at 100% coverage, the description adds meaningful usage nuance: depth values correspond to hop counts and gap-recovery behavior, 'standard' is default, 'thorough' requires a paid plan, and the question field accepts broad multi-part natural language. This enriches the schema's enum descriptions with practical context.

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

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

The description defines deep_research as grounded multi-source research over 1,455 structured sources, explicitly distinguishing it from open-web search and naming the sibling alternative ask_pipeworx. It gives concrete use-case examples and describes the output packet, making the 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 explicitly states when to use deep_research (broad/multi-part structured-data questions) and when not to (single lookups, breaking/current-news, unsigned-in users), naming ask_pipeworx as the alternative in each case. It also covers account requirements and tier limitations.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint ensuring safe usage. The description adds valuable behavioral context: returns top-N most relevant tools with full input schemas and curated examples, ready to call directly. 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?

Single paragraph with efficient sentences. Front-loaded with the primary action. Could be slightly more structured, but 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?

For a discovery tool with no output schema, the description thoroughly explains what it returns (tool names, descriptions, full input schemas with examples) and that results are callable immediately. It also mentions the top-N relevance ranking. No gaps.

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

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

All 6 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds example query phrases (e.g., 'look up FDA drug approvals') and lists many domains, which provides helpful context beyond the schema but does not add meaning to individual parameters.

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

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

The description specifies the exact action ('Find tools by describing the data or task') and the resource (tools available). It lists concrete example domains (SEC filings, financials, etc.), making it clear and highly distinguishable from sibling tools, none of which are general discovery 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 states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context for when to use it. Lacks explicit 'when not to use' instructions, but the guidance is strong.

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 beyond annotations by detailing data sources, return fields, and known issues (USPTO PatentsView API sunset May 2025, soft-fails). Annotations confirm read-only, non-destructive behavior, and the description adds operational context 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 relatively long but well-structured: starts with example queries, then the main capability, then return fields and caveats. Every sentence conveys useful information, though some internal lists could be slightly more compact. It earns its length given the tool's complexity.

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

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

Despite lacking an output schema, the description fully enumerates the returned fields with examples. It covers prerequisites (input format), dependencies (resolve_entity for names), and status of external APIs. This is sufficient for an agent to decide when to invoke the tool.

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

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

All parameters are documented in the schema (100% coverage). The description adds constraints (ticker or zero-padded CIK, names not supported) and clarifies the purpose of the 'type' parameter, which the schema already specifies. This is a meaningful addition but the schema already does substantial work.

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: 'full cross-source profile of a US public company in ONE parallel call'. It provides example queries and specifies the resources aggregated (SEC, XBRL, USPTO, news, GLEIF), differentiating it from single-pack lookups and sibling tools like resolve_entity.

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 advises when to use this tool ('when the user asks for a holistic view') and when to use alternatives ('names not supported — use resolve_entity first'). It also emphasizes preferring this over chaining multiple lookups.

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

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

The description aligns with annotations (destructiveHint=true, readOnlyHint=false) by confirming deletion. While it does not add new behavioral details beyond annotations, it is consistent and sufficient for a simple operation.

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

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

Two sentences with no unnecessary words. The action and use cases are front-loaded, making it efficient for an agent to parse.

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

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

For a tool with one parameter, no output schema, and clear annotations, the description covers purpose, usage, and how it relates to sibling tools. It is complete for this complexity.

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

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

Schema coverage is 100%, and the parameter 'key' is already described in the schema as 'Memory key to delete'. The description adds no additional meaning beyond that.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and names the resource ('memory'). It distinguishes itself from siblings by mentioning 'remember' and 'recall' as paired 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 provides three use cases: stale context, task completion, and clearing sensitive data. Also notes pairing with 'remember' and 'recall', giving clear guidance on 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, indicating a safe, read-only operation. The description adds context by explaining the fetches and extraction process, aligning with annotations. It does not contradict them and provides useful behavioral details 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 consists of three concise sentences: purpose, process, and use cases. No extraneous words, and it is front-loaded with the key action. 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?

Given the tool has only 2 parameters, no output schema, and simple behavior (read-only file generation), the description fully covers the necessary context, including output format ('single text blob') and placement guidance. It is complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters well-described. The description adds no new meaning beyond the schema's existing descriptions (e.g., url and max_links already include defaults and limits). Baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the target AI crawlers. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation rather than scanning.

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 use cases (client site indexing, personal projects, auditing competitors) and implies when to use it. It lacks explicit when-not-to-use or alternative tools, but the context is clear and sufficient for the agent.

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 and destructiveHint=false; description adds concrete return field details, adding value beyond annotations.

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

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

Two sentences, front-loaded with the core action and data, 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?

Despite no output schema, the description lists the return fields and explains usage, providing sufficient completeness for a read-only listing 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%; the description does not add extra meaning beyond what the schema provides for the include_inactive parameter, 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 states it lists the caller's active subscriptions and specifies the return fields, clearly distinguishing it 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?

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive behavior. The description adds valuable context: 'Keyless, offline' meaning no authentication and local execution, which goes 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?

The description is concise: two sentences that immediately state the purpose and key usage details, with no unnecessary 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 one-parameter tool with rich annotations and no output schema, the description sufficiently covers purpose, input format, and key behavioral traits (offline, keyless). The return value is obvious from the tool name.

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 examples. The description adds format rules not fully covered in the schema description (e.g., word separators), providing extra clarity 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 'Decode Morse code back to text', using a specific verb and resource. It distinguishes from the sibling tool 'morse_encode' which performs the reverse operation.

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 input format details (letters separated by spaces, words by '/' or double space) and notes 'Keyless, offline'. However, it does not explicitly state when to use this tool versus alternatives like 'morse_encode'.

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, etc. Description adds 'keyless, offline' but no further behavioral traits. No contradiction with annotations.

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

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

Single sentence with 12 words, front-loaded with action and output format. No unnecessary 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?

For a simple tool with one parameter and no output schema, the description fully explains purpose and output format. 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% for the single parameter, and description does not add meaning beyond the schema's property 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 explicitly states 'Encode text to Morse code' with specific formatting details, and distinguishes from sibling tools like morse_decode.

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?

No explicit when-to-use guidance; however, the 'Keyless, offline' qualifier gives context on requirements. Lacks comparison to alternatives like spell_nato.

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 only indicate non-read-only, non-idempotent behavior, so the description carries the transparency burden. It adds substantial behavioral details: rate-limited to 5 per identifier per day, free and not counting against quota, returns a claim_token when filed without an account, and signals that the team reads digests daily. This goes well beyond the annotation flags.

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

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

The description is longer than average, but every sentence earns its place by adding a rule, constraint, or workflow step. It is front-loaded with the core purpose and then layers usage scope, token mechanics, and rate limits without redundancy.

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

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

Given there is no output schema, the description adequately explains return behavior (claim_token, later status check) and covers workflow, exclusions, rate limits, and team response. It is complete for a feedback tool with this 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?

Although the schema already describes all parameters at 100% coverage, the description enriches meaning by explaining how to use them together: it tells users to describe issues in terms of Pipeworx tools/packs (not end-user prompts) and details the claim_token workflow ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This adds practical guidance that the schema alone lacks.

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 verb+resource ('Tell the Pipeworx team') and specifies the exact purpose: reporting broken/missing/existing functionality. It distinguishes itself from sibling tools like ask_pipeworx (asking questions) and discover_tools (exploring capabilities) by centering on tool 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?

The description explicitly enumerates when to use the tool (bug, feature/data_gap, praise) and provides a strong exclusion: only for tools served by this Pipeworx connection, with a clear alternative ('file it with that server instead'). It also explains the claim_token follow-up workflow, giving an actionable after-use path.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds valuable behavioral details: it's self-aggregating from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. No contradictions with annotations.

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

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

The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. No redundant or vague language.

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 optional param, no output schema), the description covers the key return elements (top tools, top packs, total call volume), caching, and use cases. It could mention the exact format of the response, but the description is sufficient for the agent to understand what it will get.

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 coverage is 100% with one parameter (window) having enums and description. The description adds semantic context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds 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?

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window (24h, 7d, 30d). It uses a specific verb ('returns') and resource ('trending data on Pipeworx'), distinguishing it clearly from sibling tools like discover_tools or ask_pipeworx.

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

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

Description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment) and mentions caching behavior. While it doesn't explicitly say when not to use it, the use cases are specific enough to guide the agent. No direct sibling comparison is needed because the tool's purpose is unique.

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: true, idempotentHint: true, destructiveHint: false) clearly indicate no side effects. The description goes far beyond annotations by detailing internal logic: semantic anchor with Jaccard similarity threshold, partition filter that drops placeholder slugs, and fill check that checks live CLOB depth. It warns when signals should not be traded (realizable_edge_pp <= 0). This is highly transparent.

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

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

The description is long and dense with technical jargon (monotonicity violations, partition-sum checks, Jaccard similarity). While it is well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), it could be more concise. Approximately 280 words; trimming could improve readability without losing essential detail.

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

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

The tool has no output schema, but the description comprehensively explains the response structure (opportunities[], partition_check object with fields). It covers edge cases (skipped_low_similarity, placeholders_filtered) and gives detailed behavior for event and topic modes. Given the tool's complexity and zero output schema, the description is as complete as needed.

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

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

Schema coverage is 100% with both parameters documented. The description adds significant meaning: event accepts slug or URL, topic accepts seed questions. It explains behavior for each parameter (e.g., topic mode searches related events, flattens markets, runs comparator). This adds 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's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two distinct modes (event and topic) with clear verb+resource relationships, and it distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection rather than edge tracking or 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?

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan,' 'event (recommended for a specific market),' and 'topic (for cross-event scanning).' It explains the strengths of cross-event mode over single-event mode. However, it lacks explicit 'when not to use' statements, such as pointing to polymarket_fill_risk for custom sizing (though it mentions that tool at the end).

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds significant behavioral detail: caching at KV level keyed on knobs, model family internals, Fed bet exclusion rationale, and diagnostics for empty segments. 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?

Description is verbose with deep technical details (e.g., 'lognormal barrier from 90d FRED log-returns', 'per-sport α (tennis 1.02, soccer 1.10, MMA 1.15)'). While structured with segments and knobs, it could be more concise. First sentence effectively fronts purpose, but subsequent detail is dense.

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, so description must explain return structure. It does so thoroughly: by_segment, fed_candidates/fed_note, _diagnostics, and per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h move warning). Covers filtering rationale and why Fed bets are excluded. Complete for a complex tool.

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

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

Schema covers all 9 parameters with descriptions, so baseline is 3. Description adds practical usage context (e.g., min_liquidity 'Set to 5000 to drop thin-book opportunities', slippage_pp advice). Provides value beyond schema, justifying +1.

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 starts with clear verb 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price' and explicitly targets 'what should I bet on today'. It distinguishes three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and contrasts with siblings by focusing on edge discovery rather than arbitrage or tracking.

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

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

Description explains when to use ('what should I bet on today') and provides filtering knobs (min_liquidity, max_spread_pp, etc.) but does not explicitly state when not to use or compare with alternatives like polymarket_arbitrage. Context implies differentiation but lacks direct exclusion guidance.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds significant behavioral context: it explains the returned structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL, snapshot gaps), and data granularity (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 verbose but well-structured, front-loading the purpose and using clear formatting for output fields. Every sentence adds value, though slight trimming could improve conciseness without losing 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?

No output schema is provided, but the description thoroughly explains the output structure (tracked, expired, snapshot_dates) with field-level details and limitations. For a telemetry tool, this is highly complete.

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

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

Schema description coverage is 100%, but the description adds meaning: it explains that 'days' defaults to 14 and clamps to 2-30, and 'window' defaults to '1wk' and describes snapshot families. This supplements the schema with practical usage context.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical analysis rather than current snapshots.

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

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

The description implicitly guides usage by contrasting fresh vs. stale edges ('a 3-week-old wide edge is wide for a reason nobody is willing to take'). It does not explicitly state when not to use, but the context is clear. Alternatives are implied by sibling tools but not named directly.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already indicate safe read-only behavior. Description adds substantial behavioral context beyond annotations: it walks the order book ladder, returns specific fields (slippage, verdict, forced_directional_risk), and describes per-leg fill details for basket mode. No contradictions.

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

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

Description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, usage guidance) and front-loaded purpose. However, it is somewhat verbose with detailed return field lists, which would be more appropriate in an output schema. Still, every sentence earns its place, and the 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 (two modes, 4 parameters, no output schema), the description is remarkably complete. It covers both modes thoroughly, explains return fields, provides usage guidelines, warns about risks (partial fills, forced directional risk), and specifies thresholds. No gaps for an AI agent to understand invocation.

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%, baseline 3. Description adds semantic value beyond schema: clarifies that size_usd for single-market is 'max spend on buys, target proceeds on sells' and for basket is 'settlement notional — shares per leg'. Also explains side defaults. This extra context justifies a 4.

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

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

Description clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' with distinct modes (single-market and basket) and return fields. It uses specific verbs like 'check', 'walks the ladder', and 'returns', distinguishing it from trading-oriented siblings like 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?

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable on thin books, partial basket fills converting arb into unhedged directional position). Provides clear when-to-use and when-not-to-use context.

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

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

Annotations already indicate read-only and idempotent behavior. The description goes well beyond by detailing the two modes, response fields (leg-by-leg prices, top_spreads_pp), safety fields (compatibility_warning, temporal_alignment), and skip counters. It also explains conditions when spreads are meaningless, adding substantial behavioral context 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 quite lengthy (>200 words) but well-structured with bold headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, but some content could be more concise. The front-loading is effective, but the density may overwhelm an AI 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?

Given the complexity of the tool (cross-venue, multiple modes, safety checks) and the absence of an output schema, the description covers everything needed: response format, safety fields, skip counters, and temporal alignment. It is complete and leaves no critical gaps for an agent to use the tool effectively.

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

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

Input schema covers all 3 parameters with descriptions (100% coverage). The description adds value by listing the exact pre-mapped topics for the 'topic' parameter and explaining the override behavior for explicit tickers. Examples are provided. This enhances understanding beyond the schema alone.

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

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

The description explicitly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on multi-venue comparison and details two modes (topic and explicit tickers). The verb and resource are clear.

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 strong context for when to use the tool, including explanations of the two modes and safety fields. It warns that pre-mapped topics may not be tradeable and that compatibility_warning indicates non-equivalent bet shapes. However, it does not explicitly contrast with alternatives like polymarket_arbitrage, slightly reducing clarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to user identifier, beyond what annotations provide. 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 plus scoping note. No fluff, front-loaded with core action.

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 1 parameter, high schema coverage, and annotations, the description fully explains behavior. No output schema, but functionality is clearly described.

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

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

Schema covers 100% of parameters with description for 'key'. Description essentially restates schema info, adding no new meaning. Baseline 3.

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

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

The description clearly states the tool's purpose: retrieve a value saved via remember, or list all saved keys if key is omitted. It distinguishes itself from sibling tools like remember and forget.

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

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

Explicitly says when to use: to look up previously stored context without re-deriving. Mentions pairing with remember and forget, providing clear usage context.

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

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

Description states mark_read flags events as read, implying state mutation, but annotations declare readOnlyHint=true, creating a direct contradiction. According to rules, this forces a score of 1.

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, front-loaded with purpose, no redundant sentences. Every sentence adds useful information.

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

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

Despite no output schema, description details returned fields (source, citation_uri, payload). Covers all parameters, polling behavior, and alternative access method. Complete for this 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%, so baseline is 3. Description adds value by giving examples (e.g., 'sec_8k' for type) and clarifying that mark_read affects next call. Exceeds baseline.

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

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

Description clearly states it pulls fired events from subscription feed, using specific verb 'Pull' and resource 'fired events from your subscription feed'. It distinguishes itself from sibling tools by focusing on recent alerts from persistent feed.

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

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

Provides guidance on filtering by type and since, explains mark_read behavior for polling, and notes an alternative GET endpoint for scripts/dashboards. Lacks explicit when-not-to-use but offers sufficient context.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral details: fans out in parallel to multiple sources, fallback mechanism (GDELT→GNews), soft-fail for USPTO, and response format (changes grouped by source, total_changes count, citation URIs). 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?

Description is detailed but well-organized: starts with examples, then explains data sources, parameter syntax, return structure, and when to use alternative. Front-loads key information. Slightly verbose but 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?

Despite no output schema, description explains return structure (changes[], total_changes, citation URIs). Covers all needed context: sources, fallbacks, parameter options, and distinguishes from sibling. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for all three params. Description adds extra context: 'type' is limited to 'company', 'since' accepts ISO date or relative shorthand with examples, 'value' can be ticker or zero-padded CIK, and recommends default '30d' or '1m'.

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 starts with clear example queries and states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists data sources (SEC EDGAR, GDELT→GNews, USPTO) and distinguishes from sibling tool entity_profile.

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

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

Explicitly states when to use ('What's new', 'latest', 'updates') and when not to ('Use entity_profile instead when you want the static profile...'). Provides example queries and typical usage like '30d'.

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 idempotentHint=true and destructiveHint=false, so the tool is safe to call multiple times and not destructive. The description adds value by explaining the write behavior, key-value storage, scoping by identifier, and session-based persistence. There is no contradiction with annotations.

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

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

The description is concise, front-loading the main purpose and usage, then providing details on storage semantics and alternatives. 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?

Given the simplicity of the tool (2 parameters, no output schema, no nested objects), the description provides all necessary context: what is stored, when to use, how it is scoped, persistence duration, and relationship to siblings. Annotations cover idempotency and non-destructiveness.

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 provides 100% coverage with clear descriptions for both parameters (key and value). The description adds context by explaining that the key should be a mnemonic like 'subject_property' and the value can be any text. Since schema already does the heavy lifting, this is above baseline 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's purpose: 'Save data the agent will need to reuse later.' It specifies the action (save), the resource (data), and provides concrete examples like 'resolved ticker, target address, user preference.' It also distinguishes from sibling tools by mentioning 'Pair with recall to retrieve later, forget to 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?

The description explicitly states when to use the tool: 'when you discover something worth carrying forward.' It provides context on scoping ('scoped by your identifier') and persistence differences ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours'). It also names alternatives: recall 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?

Beyond the annotations (read-only, open-world, idempotent, non-destructive), the description discloses valuable behaviors: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI are unavailable, and explicitly lists unresolved identifiers under `unresolved` rather than omitting them. This adds significant context beyond annotations.

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

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

The description is somewhat long but well-structured, starting with user-facing examples to aid recognition, then defining purpose and supported types. Each section adds value, though some examples are repetitive and could be trimmed without losing 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?

With no output schema, the description carries full responsibility for explaining return values. It thoroughly covers identifiers returned per type (CIK, ticker, LEI, FIGI, RxCUI), source labeling, unresolved handling, and fallback behavior. The richness of detail fully equips an agent to understand the tool's 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% for both parameters, so the baseline is 3. The description adds helpful clarifications (accepted formats for company and drug, example values like 'ozempic'), but these mostly reinforce the schema rather than introduce new meaning. No additional parameter nuances are revealed.

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 resolves user-spoken names to canonical identifiers, with a specific verb and resource. It distinguishes from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID' and details supported types (company, drug) with concrete examples like ticker and CIK.

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

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

It provides a clear use case ('Use FIRST whenever you have a name but need an ID') and contextual details like graceful degradation. However, it does not explicitly name alternative tools to use when an ID is already available, nor does it state when not to use this tool, falling short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a 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?

Three sentences, front-loaded with purpose, then details on behavior and use case. Every sentence adds value, no fluff.

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

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

Despite no output schema, the description clearly describes the return value: ranked list with score, confidence, signal density per entity. It also explains the internal probe mechanism (ai_visibility_check). Complete for a comparison tool.

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

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

Schema coverage is 100%. The description adds meaning beyond schema: explains that the first entity is treated as 'subject' and rest as competitors, and that context disambiguates common names. It does not cover all parameters in depth but provides useful context.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side', with a specific verb ('compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' It implies when to use but does not explicitly state when not to use or name alternatives beyond the listed siblings.

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

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

Adds valuable behavioral context beyond annotations: it fans out to two services, handles partial failures gracefully, and mentions bundlephobia's first measurement may take 5-30s. Annotations already declare readOnlyHint=true and idempotentHint=true, so description complements them well.

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

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

Description is longer but front-loaded with main purpose. It efficiently conveys composite nature, usage context, return format, and limitations. Slightly verbose but 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?

Description fully covers what the tool does, its return value (summary block, advisories, links, versions), limitations (NPM only, timeout), and partial failure behavior. No output schema exists, so description must provide this, which it does.

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

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

Schema covers both parameters with descriptions. The description adds little beyond the schema (e.g., 'npm package name', 'specific version'), 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: a composite check for npm packages aggregating data from deps.dev and bundlephobia. It specifies what it covers (license, advisories, version history, bundle size, etc.) and is distinct 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 states when to use ('is X safe/popular/small', 'what does adding lodash cost me') and provides exclusions (NPM only; other ecosystems handled by deps.dev:version directly).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds internal details: BGE-base-en embeddings, 500-char windows, 200K char cap with truncation, and offset information. 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 a single paragraph of ~120 words, front-loading purpose and then providing details. Every sentence adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity (3 params, no output schema), the description covers input, algorithm, limits, and behavior. It also explains pairing with another tool, making it complete 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% for all 3 parameters. The description adds value by providing example queries (e.g., 'supply-chain risk') and clarifying defaults ('limit 1-20, default 5').

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' using a 'natural-language query'. It specifies the verb 'search' and resource 'inside a fetched record', distinguishing it from siblings by mentioning it pairs with 'ask_pipeworx_grounded'.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also mentions pairing with another tool, but could be more explicit about 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds 'keyless, offline,' which provides additional behavioral context about operation without keys and local execution. It does not explain the output format but it is implied by the NATO spelling.

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-loaded with the primary action and use case. Every word adds value; no superfluous 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 transformation tool with one string parameter, no output schema, and comprehensive annotations, the description covers purpose, usage, and behavioral traits (keyless, offline) completely. No gaps are apparent.

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 meaning by specifying 'NATO phonetic alphabet,' which clarifies how the input text is transformed. This goes beyond the schema's property description 'The text to spell.'

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 (spell), resource (text), and method (NATO phonetic alphabet) with an example. It distinguishes itself from siblings like morse_encode by specifying a different encoding scheme.

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

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

It provides a clear use case ('Great for reading codes/confirmation numbers aloud') and mentions keyless, offline operation, which implies when to use. However, it does not explicitly state when not to use or compare with alternatives like Morse code.

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: requires OAuth account, returns subscription ID, specifies delivery channel details, phone verification requirement, SMS daily cap of 10, webhook signing, and auto-disable after 10 failures. No contradictions with annotations.

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

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

The description is detailed but well-structured with clear sections for types and delivery channels. It is slightly long but front-loaded with the core action. 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?

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers return value, required accounts, rate limits, and failure behavior. It is sufficiently complete for an agent to use the tool correctly.

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

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

Schema coverage is 100% and the description enriches parameters with detailed examples and constraints for each type, such as sec_8k items codes, polymarket_edge topic, and delivery options. This provides meaning beyond the schema's basic 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 creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions by explaining what it does.

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

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

The description provides clear when-to-use context by listing supported subscription types and delivery channels. It also mentions prerequisites (Pipeworx OAuth account, phone verification for SMS) but does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds significant context about being an onboarding tool returning categorized examples from a live catalog, adding value 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?

Long but front-loaded with common queries and well-structured with categories and usage patterns. Some redundancy but overall efficient for the context.

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 explains return content (category-bucketed examples with tool signatures) and covers both full spread and topic-focused usage. Complete for its role.

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

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

Schema coverage is 100% with one optional parameter described. Description enriches with example focus areas and default behavior, but baseline 3 is appropriate as schema already does the heavy lifting.

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

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

Description clearly states it is the onboarding entry point providing categorized example questions with tool+argument shapes, and distinguishes from siblings by being the first tool to use when the agent doesn't know capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and describes calling with no arguments or with a topic, 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 annotations, the description clarifies that the row is deactivated (not deleted) and ownership is enforced, adding valuable behavioral context that annotations 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?

Two sentences, concise and front-loaded, with 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?

For a simple tool with one parameter and no output schema, the description covers ownership, deactivation effect, and historical impact, which is complete enough.

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

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

Schema coverage is 100%, so the description does not need to add much. It mentions 'by id' but no further syntax details; the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('cancel') and resource ('subscription'), clearly distinguishing from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description mentions ownership enforcement ('you can only cancel your own subscriptions') and the effect on historical data, providing clear context for when to use the tool. However, it does not explicitly compare with alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond annotations: it defines the verdict enum, distinguishes the meaning of could_not_verify (check did not happen, with error structure) from unsupported (no source), and notes that evidence includes pipeworx:// citations. This is exactly the kind of extra transparency that helps callers interpret results correctly.

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

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

The description is long but every sentence carries essential information: examples, routing logic, return types, edge cases, and the efficiency gain. It is well-structured with clear separations between when-to-use, how routing works, what is returned, and critical warnings. No filler or repetition.

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 is complex (two routing paths, multiple verdicts, error handling) and has no output schema. The description covers the return format (verdict, actual value, citation, reasoning), explains the subtle difference between could_not_verify and unsupported, and hints at the underlying pipeline. This is sufficient for an agent to call the tool and interpret results 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%; both 'claim' and 'tolerance_pct' have descriptive comments in the schema. The tool description adds context about the default tolerance behavior and the use of percent-delta math, but it does not add meaning beyond what the schema already provides for the parameters. 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 opens with explicit natural-language examples ('Is it true that…', 'fact check') that make the tool's purpose unmistakable. It clearly specifies a noun phrase: natural-language claim verification against authoritative sources, and distinguishes itself from siblings by describing the structured SEC EDGAR fast path vs. grounded pipeline.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and explains two routing paths. It does not explicitly mention sibling tools or say when not to use, but it positions itself as the replacement for 4-6 sequential calls, providing clear context for when it is appropriate.

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