Color Pizza

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

Annotations already provide safety hints (readOnly, idempotent, openWorld). The description adds valuable context: default model is free, Anthropic requires BYO key, returns per-model and combined view. No contradictions.

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

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

Every sentence adds value, front-loaded with purpose. No redundant text. Efficiently covers key points in few sentences.

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

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

Despite no output schema, the description explains the return format (per-model and combined). Given annotations and schema richness, it is adequately complete for a probe tool. Minor gap: no mention of rate limits or error handling.

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

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

Schema coverage is 100% with clear descriptions. The description adds context (default model, key usage) but does not significantly elaborate on parameter semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs ('probe', 'score') and resources ('LLMs', 'visibility'). It clearly distinguishes the tool's niche (AI-marketing audits, brand checks) from siblings like scan_competitor_ai_presence.

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 mentions use cases (audits, pre-launch checks, competitive monitoring) and clarifies default vs. BYO-key models. However, it lacks explicit when-not-to-use guidance or direct alternatives.

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

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

The description adds substantial context beyond the annotations: it reveals the routing behavior across 5,502 tools, the filling of arguments, the production of pipeworx:// citation URIs, and the fact that it works on every tier with one fast call. It even notes how breaking-news queries are handled. There is no contradiction with the readOnly, openWorld, or idempotent hints.

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

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

The description is long but every section earns its place: primary directive, domain list, usage triggers, examples, alternatives, and special-case handling. It is front-loaded with the most important guidance and structured logically, with no unnecessary fluff.

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

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

Since there is no output schema, the description explains the return value as a structured answer with stable pipeworx:// citation URIs. It also clarifies the tool's position among siblings, mentions cross-tier availability, and provides enough context for an agent to decide when to use it versus alternatives. This is complete for a tool of 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?

The input schema has 100% coverage with a clear 'question' parameter and five aliases, so the baseline is 3. The description adds value by providing concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected natural-language input, helping the agent select appropriate phrasing.

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 a specific verb+resource: it routes factual questions to 5,502 tools across 1,442 verified sources, fills arguments, and returns structured answers with stable citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, establishing its role as the default entry point.

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

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

The description gives explicit when-to-use triggers: any factual question using phrases like 'what is', 'look up', 'find', 'get the latest', 'how much', or 'current', even if web search could answer it. It names alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, and states it works on every tier.

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), the description discloses live candidate enabling, current inactive state, and that it is a fully working router ('falls back to nothing' clarified). It adds meaningful behavioral context about runtime variability and continuity.

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 with front-loaded identity and all key facts (experimental status, current state, usage guidance). Slightly verbose with minor redundancy ('identical' and 'exactly like') but every sentence earns its place.

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

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

The description covers the tool's identity, experimental behavior, current state, usage direction, and relationship to the stable router. It also states the response shape matches ask_pipeworx, making it complete despite lacking 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?

Schema coverage is 100% with the 'question' parameter and all aliases documented. The description only says 'same arguments' as ask_pipeworx, which doesn't add new parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly identifies this as a beta universal router identical to ask_pipeworx, with specific scope (5,502 tools) and a distinct experimental edge. It differentiates from the stable sibling by emphasizing candidate routing improvements and current matching behavior.

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

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

Explicitly states when to use ('when you want the newest routing') and names the stable alternative (ask_pipeworx) for comparison. It also explains that results are compared with the stable router to decide merges, providing clear context for experimental vs stable 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?

Discloses refusal behavior with specific refusal_reason enums, output shape with evidence and confidence, and that it uses only tool result contents. Annotations already declare readOnly/idempotent, but the description adds refusal semantics and the grounded-extraction guarantee without contradicting 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?

Five sentences, each serving a distinct function: positioning, mechanism, output contract, usage criteria, and cost/tradeoff. Structurally efficient, no filler despite its length.

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

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

Provides the complete behavior contract including success and refusal payloads, use cases, and comparative cost. With no output schema, the description compensates by fully specifying return shapes and refusal reasons, making it self-sufficient for an agent.

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

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

The input schema covers all six parameters (question plus five aliases) with 100% clarity, so the description need not repeat them. The description adds no parameter-specific semantics, but schema already defines each alias and the natural-language question format, warranting the 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and contrasts with ask_pipeworx, clearly distinguishing the grounded answering behavior from the sibling tool. It states the routing mechanism and extraction logic, making the purpose specific and actionable.

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 instructs when to use: 'Use whenever an answer will be quoted, cited, or acted on' and when to avoid: 'prefer ask_pipeworx for casual lookups.' Also notes the extra LLM call cost, providing a clear tradeoff vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context beyond annotations: resolution confidence handling, closed market detection, wide spread warnings, cancellation rule parsing, and fan-out behavior. No contradiction with annotations.

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

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

The description is detailed and informative, covering many edge cases and behaviors. While somewhat lengthy, the structure is logical: main action, usage, classifiers, examples, response shapes, safety notes, and cancellation rules. It could be slightly more concise but is well-organized.

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

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

Given the tool's complexity (multiple data sources, resolution logic, safety paths) and no output schema, the description is remarkably thorough. It covers market match confidence, parent events, news fallback, wide spreads, cancellation rules, and all blocking paths. No missing critical information.

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

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

Schema coverage is 100% for 3 parameters. The description adds meaning by explaining that 'market' can be a slug, URL, or text, and describing depth options and include_raw behavior. Examples are provided, adding 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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). It distinguishes from sibling tools like ask_pipeworx or polymarket_edges by being a consolidated, multi-source research 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?

Explicit usage examples are given: "Use for 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'". It also provides fan-out examples for different bet types. However, it does not explicitly state when not to use this tool or 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?

The description adds significant behavioral context beyond annotations: explains data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), handles off-calendar fiscal years, results sorted by primary metric, and returns citation URIs. Annotations already indicate read-only, idempotent behavior.

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

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

The description is front-loaded with example queries and is concise given the amount of information. Slightly dense but efficient; minor room for improved structure.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs) and handles edge cases like off-calendar fiscal years. Covers all necessary context for effective tool 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 concrete examples for values (tickers/CIKs for company, drug names), constraints (min 2, max 5), and clarifies behavior of type parameter.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with specific data sources and metrics. It distinguishes from sibling tools like entity_profile by emphasizing parallel lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. However, it does not explicitly state when not to use (e.g., for more than 5 entities).

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

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

The description goes far beyond the readOnly/openWorld/idempotent hints by explaining return structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citations), gap handling (gaps[] explicit, never invented), contradiction scanning, semantic excerpting, hop fields, and expected latencies (15-60s, thorough up to ~90s). This is rich behavioral context that annotations alone do not provide.

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

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

The description is lengthy but every sentence adds actionable detail for a complex tool. It is front-loaded with the critical account requirement and alternative, then moves through purpose, usage, depth semantics, and return format. While not as terse as the two-sentence TDQS high example, the density is justified by the tool's scope; it avoids redundancy and 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?

Given the tool's complexity, the description fully covers purpose, prerequisites, alternatives, parameter behavior, return packet structure, citations, contradictions, gaps, performance expectations, and non-invention guarantees. There is no output schema, so the description carries the entire burden of explaining outputs, and it does so comprehensively.

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% with detailed depth descriptions, so the baseline is 3. The description adds value by explaining the practical consequences of each depth level (e.g., standard does gap recovery and contradiction scan, thorough is paid and chases leads) and by giving example question types. This enriches parameter understanding beyond the enum strings.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1442 STRUCTURED data sources' in one call, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx (single lookup), so an agent understands exactly what this tool does and how it differs from siblings.

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

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

It tells when to use the tool: 'Best for broad/multi-part questions over structured data' and provides alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and that ask_pipeworx works without sign-in, plus depth-specific guidance (quick/standard/thorough) with concrete behaviors.

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 idempotentHint=true. The description adds context about returning top-N relevant tools with full schemas and examples, and that each result is ready to call directly. This supplements the annotations without contradicting them.

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

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

The description is well-structured with the core purpose front-loaded. It is slightly verbose (4 sentences) but each sentence adds value. Could be slightly more concise, but overall efficient.

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

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

The description is complete for a discovery tool: explains what it does, when to use it, what it returns (top-N tools with names, descriptions, and schemas), and provides aliases. No output schema exists, but the description sufficiently explains the output format.

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 all parameters described. The description does not add extra parameter details beyond what the schema provides, but the schema examples give useful context. Baseline score of 3 is appropriate given full schema coverage.

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

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

The description clearly states 'Find tools by describing the data or task' and distinguishes this tool from siblings by emphasizing discovery. It provides concrete examples of domains (SEC filings, FDA drugs, etc.) and specifies that results are ready to call directly, setting it apart from other 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?

The description explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists numerous domains where discovery is appropriate, giving clear context for when to use this tool over others.

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 read-only, idempotent, safe. Description adds detailed behavior: fans out across multiple sources, returns specific fields, USPTO sunset May 2025 soft-fail, and exact output structure. No contradiction.

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

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

Long but every sentence adds value; front-loaded with examples and usage priority. Could be slightly more concise but effectively structured.

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

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

No output schema, so description carries full burden. It fully explains returned fields, data sources, and potential failures. A slight gap in specifying exact output structure is acceptable given free-text.

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

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

Schema coverage is 100% with descriptions. The description reinforces parameter usage with examples and adds crucial context about name resolution, going beyond the schema's minimal definition.

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

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

The description starts with example user queries, specifies the verb ('profile' implied), and the resource ('US public company'). It explicitly contrasts with chaining single-pack lookups, clearly distinguishing its purpose 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?

Directly states when to use ('holistic view') and when not (if only a name, use resolve_entity first). Provides clear alternatives and context for invocation.

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data but no additional behavioral traits beyond what annotations cover.

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 front-loaded with the action. No wasted words; every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, usage context, and related tools. It does not specify behavior for non-existent keys, but idempotency hints handle that.

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

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

Schema coverage is 100%, and the description adds no new information about the 'key' parameter beyond what the schema provides. 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 deletes a memory by key, with a specific verb and resource. It distinguishes itself from sibling tools 'remember' and 'recall' by explicitly mentioning them as counterparts.

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 scenarios (stale context, task completion, clearing sensitive data) and mentions related tools. Does not include explicit when-not-to-use, but the guidance is sufficient.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it fetches the page, extracts title/description/key links, and emits a standard format. No contradictions. It provides behavioral context beyond annotations (e.g., 'production-ready', network fetch).

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 followed by a clear list of use cases. No redundant words. Primary purpose is front-loaded. 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, the description explicitly states the output format ('standard llms.txt markdown format') and deployment location ('site-root/llms.txt'). With only two parameters and simple behavior, this is fully 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 describes both parameters with 100% coverage. The description does not add significant extra meaning beyond mentioning 'url' implicitly and 'max_links' default/max values. 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 a clear verb and resource: 'Generate a production-ready llms.txt file for any URL'. It specifies the target audience (AI crawlers like ChatGPT, Claude, Perplexity) and the action (fetches, extracts, emits). This differentiates it from sibling tools 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?

Explicitly lists three use cases: getting a client's site indexed, drafting for own project, auditing a competitor. While it doesn't state when not to use it or name alternative tools directly, the provided contexts are sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specific output fields (titles, descriptions, etc.), which provides behavioral context beyond the annotations. No contradictions.

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

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

Single sentence plus a usage hint. No wasted words. Information is front-loaded and essential.

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 zero parameters, rich annotations, and a clear description of the output, the tool's behavior is fully specified. No output schema needed because the description enumerates returned fields.

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

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

No parameters exist. Baseline is 4 as the description does not need to add parameter information. The schema coverage is 100% (trivially). The description's mention of the output fields is sufficient.

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

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

The description clearly states the tool lists all available palettes with specific fields (titles, descriptions, color counts, licenses). It distinguishes from sibling tools by noting that the result serves as valid values for name_colors and search_color_names.

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 indicates when to use it: to discover valid values for the 'list' argument of name_colors and search_color_names. This is concise and practical, leaving no ambiguity about its purpose.

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 readOnly, idempotent, and non-destructive hints. Description adds value by listing return fields (id, type, params, created_at, last_fired_at, fire_count) and default behavior (active only) without contradicting 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: first states purpose and output, second provides usage guidance. No redundant information. Front-loaded and efficient.

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

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

Given the tool is simple (one optional param, no nested objects), the description covers functionality, usage, and return fields. No output schema, but description lists fields adequately.

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

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

Schema has one parameter with description (include_inactive). Description does not elaborate beyond the schema, but schema coverage is 100%, 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 'List the caller's active subscriptions' with specific verb and resource. It lists return fields, distinguishing from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds behavioral context: returns closest named color with canonical hex, RGB, and perceptual distance, and default list behavior. 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-load the primary purpose and include essential usage details. Every sentence adds value; 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 explains the return structure (closest name, canonical hex, RGB, distance). Parameters are fully covered, and sibling tool mention provides completeness for list options.

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

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

Schema coverage is 100% with clear parameter descriptions. The description enriches by providing examples of comma-separated hex codes and listing possible naming lists, adding significant 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 finds nearest human-friendly color names for hex colors. It matches the name and title but does not explicitly differentiate from the similar sibling 'search_color_names', though it references 'list_palettes' for available lists.

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

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

The description explains how to pass multiple hex codes (comma-separated, with/without #), optionally select a naming list, and refers to 'list_palettes' for options. It does not specify when not to use this tool but provides sufficient guidance for typical usage.

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

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

Annotations provide only generic bool hints, so the description correctly carries the transparency burden. It discloses real behavioral traits: rate limiting ('Rate-limited to 5 per identifier per day'), follow-up mechanics ('Filing without an account returns a `claim_token`; pass it back later'), and that it is free and quota-exempt. No annotation contradiction is present.

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 sentence earns its place: purpose, usage triggers, scope exclusion, privacy guidance, token follow-up, roadmap impact, rate limit, and cost. It is front-loaded with the primary action and uses clear scannable phrases, though it could arguably be tightened by merging the roadmap and quota sentences.

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

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

For a tool with no output schema, the description compensates fully: it explains what to expect (claim_token if unauthenticated), how to follow up, why the tool exists (team reads digests daily), and operational constraints (rate limit, quota exemption). The scope boundary with sibling tools is unambiguous, making the description complete for an agent to select and 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?

The input schema already covers all four parameters at 100% coverage, so the description doesn't repeat schema text. Still, it adds meaningful semantics by explaining how to use `claim_token` with a concrete invocation example (`pipeworx_feedback({claim_token:"pwfb_…"})`) and by instructing users to describe issues in terms of Pipeworx tools/packs, which directly relates to the `context` object.

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+resource ('Tell the Pipeworx team'), and clearly distinguishes the tool's purpose from siblings by enumerating feedback types (bug, feature/data_gap, praise). It also establishes the exclusive scope ('ONLY for tools served by this Pipeworx connection'), which separates it from competitor-server feedback 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?

The description explicitly states when to use the tool ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and gives a clear exclusion: feedback about another MCP server should be filed with that server. It also provides practical guidance for ambiguous cases: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds value by disclosing data source (CF analytics-engine), absence of PII, and caching behavior (5min-1h). Slight deduction because annotations already cover most safety traits.

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

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

Three well-structured sentences: core function, use cases in bullet form, and technical details. No unnecessary words; front-loaded with the most important 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?

Given the simple single-parameter input and absence of output schema, the description completely addresses what the tool returns, how to use it, and its caching semantics. No gaps for agent decision-making.

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 description for 'window'. Description enriches meaning by explaining the behavioral difference between shorter and longer windows, going beyond the enum listing.

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

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

Description uses specific verb 'Returns' and identifies the resource (top tools, top packs, total call volume) and timeframe windows. Clearly distinguishes from siblings by focusing on trending usage rather than generic discovery or search.

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 lists three concrete use cases and explains window selection trade-off (shorter for hot, longer for steady-state). Provides practical guidance on when to use the tool.

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

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

Annotations already declare readOnlyHint=true, and description adds extensive behavioral context: Jaccard similarity filter, partition placeholder filter, fill check against CLOB depth, and response structure. No contradiction with annotations.

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

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

The description is relatively long but every sentence adds value. It is front-loaded with purpose and modes, then details filters and fill check. Could be slightly condensed, but overall well-structured and informative.

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

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

Given the tool's complexity (multiple modes, internal checks, response details) and lack of output schema, the description covers all aspects: usage, filtering, fill check, and response structure. It is complete and leaves no significant gaps.

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

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

Schema descriptions are adequate (100% coverage), but the tool description significantly enriches them by explaining the effect of each parameter: event triggers single-event partition check, topic triggers cross-event scan, and no arguments triggers trending scan. Adds meaningful context beyond the schema.

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

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

The description clearly states the verb 'Find' and resource 'arbitrage opportunities on Polymarket' using specific methods. It distinguishes from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage via monotonicity violations and partition-sum checks.

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

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

Provides explicit guidance on when to use no args (trending scan), event mode (specific market), and topic mode (cross-event). Includes examples of slugs and topics, and warns against trading when fill check shows non-positive edge. References sibling tool for custom sizing.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description reveals caching (cached 1h at KV level), filtering logic (placeholder-slug filter, partition skip criteria), edge calculation (net of slippage), response structure (by_segment, fed_candidates, _diagnostics), and market-specific notes (zero fees, typical spread). 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 lengthy but well-structured with sections (model families, knobs, response structure). The first sentence immediately conveys purpose. Some sentences are dense, but all are relevant given the tool's complexity. Minor redundancy (e.g., repeating default values) could be trimmed.

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

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

Given no output schema, the description fully describes the response structure (by_segment, fed_candidates, _diagnostics) and provides diagnostics for empty segments. With 9 parameters, all are explained with defaults and behavior. Caching and tradeable-edge filters are covered. The description leaves no critical gaps for an agent to use this tool correctly.

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

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

Schema coverage is 100%, but the description adds rich context beyond schema descriptions: rationale for defaults (e.g., slippage_pp explains Polymarket fee structure and typical spread), usage guidance for tradeable-edge knobs (max_spread_pp, min_liquidity), and interplay of filters (min_kelly vs min_partition_leg_kelly). This significantly aids parameter understanding.

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

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

The description states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly defines the tool's purpose and distinguishes it from siblings by detailing unique model families and segments.

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 includes use-case guidance: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' While it doesn't explicitly exclude alternatives, the context implies this is the primary edge discovery tool, and the detailed model explanations help differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint, idempotentHint): it explains history depth bounded by 60-day TTL, snapshots written on cache-miss, data gaps meaning no scan occurred, and decay computed from daily closes not intraday. 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 well-structured and front-loaded with purpose. It uses a one-line summary, an explicit question, then details args, response structure, and limits. Every sentence adds information without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and covers edge cases (gaps, TTL, decay calculation). It leaves no major ambiguity for an AI agent to safely 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?

Input schema covers both parameters with descriptions (100% coverage). The description adds value by clarifying the clamp range for 'days' (2-30), default values, and the meaning of 'window' as snapshot family. This goes slightly beyond the schema's baseline, hence 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?

The description clearly states the tool's purpose: tracking edge persistence and decay from polymarket_edges snapshots. It answers a specific analytical question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like `polymarket_edges` by focusing on time-series and decay metrics.

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

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

The description provides clear context on when to use the tool (e.g., to differentiate fresh wide edges from old ones that nobody takes). It implicitly guides usage via the 'answers' framing, but lacks explicit when-not-to-use comparisons with alternative tools like `polymarket_edges` or `polymarket_arbitrage`.

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

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

Annotations indicate readOnly and idempotent; description adds that it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, verdict, and warns about forced_directional_risk and thin legs. 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 dense but well-structured with integrated bullets. Every sentence adds value; it's slightly verbose but appropriately so given complexity. Could benefit from explicit line breaks or bullet points, but still concise for the information density.

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

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

Even without output schema, the description exhaustively lists return fields for both modes, explains edge cases like thin legs and forced directional risk, and covers parameter interactions. Fully 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 description coverage is 100%; the description adds meaning by explaining single-market vs basket modes, default values, and how size_usd is interpreted differently per mode. Adds 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 it checks realizable vs theoretical edge against live CLOB depth, distinguishing between single-market and basket modes. The verb 'fill risk' is specific, and it differentiates from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly instructs to use before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500, and explains why (theoretical overround not capturable, partial fills cause unhedged positions). Provides clear context and alternatives.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds extensive behavioral context: explains compatibility_warning causes, temporal_alignment significance, skipped_cross_type/subtype counters, and the realistic rarity of tradeable spreads. 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 lengthy but well-structured: front-loaded purpose, then modes, response fields, safety fields. Each sentence adds value. Minor redundancy in the last sentence ('pre-mapped ≠ tradeable') repeats earlier caution.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields compatibility_warning and temporal_alignment). Covers edge cases and field semantics comprehensively.

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 by explaining each parameter's role (topic as premapped shortcut, kalshi_event_ticker overrides topic, format examples) and providing concrete examples like 'fed', 'btc', and ticker templates.

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

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

The description clearly states it calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifies two modes (topic shortcuts and explicit tickers), and differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons.

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 guidance on when to use each mode, warns that pre-mapped topics often return compatibility warnings, and explains that real spreads are rarer than the shortcut list suggests. However, it does not explicitly state when not to use the tool.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint false. Description adds scope (by identifier) and pairing with siblings, going beyond annotations without contradiction.

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

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

The description is front-loaded with the core action, then explains use cases and pairing. 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 no output schema, the description could specify return format (value or list of keys). It covers purpose, usage, scope, and pairing, but lacks explicit return type details.

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

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

Schema coverage is 100% with a description for the key parameter. The tool description adds context such as omitting key to list all and examples of key values, adding meaningful usage semantics.

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

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

The description clearly states the tool retrieves a value by key or lists all keys when omitted. It distinguishes from siblings (remember, forget) and gives concrete examples like ticker, address, research notes.

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

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

It explicitly says when to use (retrieve stored context) and how (omit key to list all). It contrasts with remember and forget 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?

The description discloses important behaviors: the mark_read parameter modifies state by flagging events as read. However, annotations indicate readOnlyHint=true, which contradicts this side-effect. The description is transparent about the mutation, but the contradiction with annotations is notable.

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

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

The description is concise and front-loaded, starting with the core purpose. Every sentence provides useful information without redundancy. It efficiently covers return values, filtering, mark_read behavior, and an alternative access method.

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

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

Given the absence of an output schema, the description adequately explains return values (source, citation_uri, raw payload) and parameter effects. It covers all key aspects: filtering, pagination (limit), reading state management, and alternative access. The information is sufficient 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?

The input schema already describes all 5 parameters (100% coverage). The description adds value by explaining the purpose of each parameter (e.g., 'Filter by type', 'ISO timestamp', 'mark_read:true to flag returned events read') and details about the return fields, providing context 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: 'Pull fired events from your subscription feed.' It specifies what is returned (source, citation_uri, raw event payload) and mentions filtering options. This distinguishes it from sibling tools like 'list_subscriptions' which manage subscriptions rather than retrieve events.

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

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

The description provides guidance on when to use the tool (polling works fine) and mentions an alternative (the same feed at a REST endpoint for scripts and dashboards). It explains the mark_read flag for managing read state but does not explicitly state when not to use this tool versus siblings.

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

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

Discloses underlying behavior: fans out to SEC EDGAR, GDELT/GNews fallback, USPTO with PatentsView sunset explanation, and soft-fail. This adds significant context beyond annotations (readOnlyHint, idempotentHint, etc.).

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 front-loading of example queries and logical flow. However, it is somewhat verbose; each sentence is informative but could be slightly more concise.

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

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

Despite no output schema, description explains return values (changes grouped by source, total_changes count, citation URIs). Covers fallback behavior, parameter nuances, and alternative tool. Very complete for a complex tool.

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

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

Input schema has 100% description coverage. Description adds meaning: explains 'since' accepts ISO date or relative shorthand with examples, recommends '30d' for monitoring, and clarifies 'value' accepts ticker or CIK. Enhances understanding beyond schema.

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

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

Description clearly states 'change feed for a company in the last N days/weeks/months', providing a specific verb and resource. It distinguishes from sibling tool 'entity_profile' by noting when to use that instead for static profiles.

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

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

Explicitly lists example queries ('What's new with X', 'latest on Y'), gives context for usage, and directly tells when not to use it ('Use entity_profile instead when you want the static profile').

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 idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds persistence scoping (authenticated vs anonymous) and that it's key-value based, providing useful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with primary purpose, no filler, efficiently packs all needed 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 2-param tool with no output schema, the description covers purpose, persistence, pairing with siblings, and parameter usage completely.

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 type and description. Description adds naming conventions (e.g., 'subject_property') and that value can be any text, giving practical usage cues beyond schema.

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

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

The description explicitly states the tool saves data for later reuse across conversations or sessions, with concrete examples like ticker, address, preference. It clearly distinguishes from sibling tools (recall, forget) by mentioning them.

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 advises using the tool when discovering something worth carrying forward, and pairs it with recall and forget for full lifecycle. No explicit when-not, but the context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive hints, but the description adds substantial behavioral context: internal cascading lookups, auto-disambiguation, output formats with citation URIs, and the fact it replaces 2-3 manual lookups. 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 somewhat long but well-structured: opens with example queries, then states purpose, then breaks down supported types with details, and ends with the 'replaces 2-3 lookups' value statement. Every sentence contributes, though it could be slightly more compact.

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 the lack of an output schema, the description fully specifies return values for each type (ticker, CIK, company_name; RxCUI, ingredient, brand) and includes citation URIs. It covers disambiguation behavior and explains the tool's role in the broader toolset. This is complete for a lookup tool with strong annotations.

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 already covers both parameters (100% coverage). The description adds value by explaining accepted input forms for each type (e.g., company accepts ticker, CIK, or name; drug accepts brand or generic) and clarifying auto-disambiguation, enriching the schema's basic examples.

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: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It provides specific examples of user queries and explicitly lists supported types ('company', 'drug') with detailed output fields, distinguishing it from siblings that consume IDs rather than resolve them.

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

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

The description gives an explicit trigger: 'Use FIRST whenever you have a name but need an ID.' This is a clear when-to-use rule. However, it does not explicitly name alternative tools or exclusion cases (e.g., when you already have an ID), so it falls short of the most comprehensive guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This goes beyond the annotations.

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

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

The description is four sentences long, front-loaded with the core action, and every sentence adds value. No wasted words.

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

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

Given the moderate complexity (4 params, no output schema), the description covers the output format (ranked list with score, confidence, signal density) and the internal mechanism (probes each entity). Annotations cover safety. The description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that the first entity is treated as the 'subject' and the rest as competitors, which is not in the schema. It also summarizes the purpose of optional parameters like 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 compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. It uses a specific verb ('Compare') and resource ('entities'), and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a clear use case ('competitive AI-marketing audits') with an example. It implies when to use this tool over single-entity checks, but does not explicitly state when not to use it or mention alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: partial failures from BundlePhobia timeouts (5-30s), graceful degradation with sources_failed field, and reliance on external services. 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 relatively lengthy but well-structured. It front-loads the main purpose and gradually adds details. Every sentence contributes meaningfully, though some 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?

Given no output schema, the description thoroughly explains the return structure (summary block with fields, per-advisory detail, links, alternative versions). It covers edge cases like partial failures and ecosystem limitations, making the tool behavior fully transparent without requiring additional reference.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description reinforces the default behavior for version (latest when omitted) and adds acceptance of scoped packages. This provides marginal extra value over the schema.

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

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

The description clearly states it performs a composite check for adding npm packages, combining deps.dev and bundlephobia data. It uses specific verbs like 'fans out' and lists exact data points (license, advisories, bundle size). It differentiates from sibling tools by specifying the npm ecosystem and the composite nature.

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

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

Explicitly says when to use: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me". It also provides a clear exclusion: other ecosystems (PyPI, Maven, etc.) should use a different tool. This helps the agent avoid incorrect invocations.

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, and non-destructive. Description adds that it returns hex codes and uses substring matching, consistent and complementary.

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

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

Two sentences, no fluff, essential information front-loaded.

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

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

For a simple search tool, description covers input (substring, optional list), output (hex codes), and references sibling tool list_palettes. No output schema needed.

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

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

Schema coverage is 100%. Description adds value by linking 'list' parameter to list_palettes and providing contextual usage from examples.

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

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

Clearly states the tool searches named colors by substring, returns hex codes, and allows optional list restriction. Distinguishes from siblings like list_palettes and name_colors.

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?

Describes when to use (substring search) and mentions optional list restriction with reference to list_palettes. Lacks explicit when-not or alternative tool comparisons.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial detail beyond annotations: uses BGE-base-en embeddings with cosine similarity over 500-char overlapping windows, cap of 200K characters with truncation flagged. This fully informs the agent of underlying mechanics and constraints.

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: first states purpose, second explains when to use, third provides technical specifics. No filler. Every sentence is essential and front-loaded. The structure is optimal for quick agent understanding.

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

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

Despite no output schema, the description covers return structure (top-N passages with offsets and similarity scores), input limits, and truncation behavior. It also notes the algorithm and windowing, giving the agent all necessary context to invoke and interpret results. No gaps identified.

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

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

Schema already covers all parameters with descriptions (100% coverage). The description adds practical examples for 'query' (e.g. 'supply-chain risk'), clarifies the 'text' limit as 'max ~200K chars', and explains that each returned passage carries an offset for quote verification. This enriches the agent's understanding of how to use parameters effectively.

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 'Semantic search INSIDE a fetched record' and lists what it returns (top-N passages with offsets and scores). The title 'Search Within a Source' matches the purpose. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded, implying it is for document-level search rather than broader search 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?

The description clearly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It also provides an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives explicit when-to-use and alternative tool guidance.

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

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

Annotations indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: requires OAuth, returns new subscription id, delivery channel limitations (phone verification, 10/day SMS cap), and webhook auto-disabling 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 lengthy but packed with necessary information. It is front-loaded with the core purpose and requirements. While it could be slightly more concise, every sentence serves a purpose.

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

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

Despite no output schema, the description mentions the return value. It covers prerequisites, all supported subscription types with examples, delivery options with limitations, and error conditions (webhook auto-disable). The context is 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%, but the description adds substantial value beyond the schema. For the 'params' object, it provides detailed examples for each type (sec_8k, polymarket_edge, etc.) and clarifies required fields like sponsor or condition for clinical_trial. The delivery object explanation includes validation rules and webhook signing details.

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

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

The description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns a new subscription ID. The verb 'subscribe' matches the tool name, and the description distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. It lists supported types and delivery channels. However, it does not explicitly mention when to avoid using this tool or directly compare to alternatives, but the sibling list provides context.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it returns dynamic examples from the live catalog and serves as an onboarding entry point. No contradictions found.

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 appropriately front-loaded with common user queries and provides all necessary information in a structured way. While it is a bit long, every sentence adds value and there is no redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema needed) and the richness of annotations, the description fully covers when and how to use it. It addresses the primary use case and leaves no ambiguity.

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 provides a clear enumeration of acceptable topic values ('finance, pharma, economics, real-estate, betting, weather, government, science, news'), enhancing the schema's description. It also explains the effect of omitting the parameter.

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 is the 'onboarding entry point' that returns 'category-bucketed example questions' with exact tool+argument shapes. It distinguishes itself from sibling tools like ask_pipeworx, entity_profile, etc., by specifying its role as a first-use resource.

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 for you' and provides instructions for calling with no arguments or with a topic parameter. The description also lists the valid topic values, making it clear when to use each option.

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 non-readOnly, non-destructive, and idempotent. The description adds valuable behavioral context: the row is deactivated (not deleted) and historical events remain accessible via recent_alerts, which is beyond what annotations provide. No contradiction with annotations.

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

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

The description is two sentences with front-loaded purpose ('Cancel a subscription by id'), immediately followed by constraints and behavioral details. Every sentence provides critical information without extraneous words.

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

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

Given the tool's simplicity (1 parameter, no output schema, annotations present), the description fully covers purpose, ownership constraint, persistence behavior, and relationship to other tools. No gaps remain for this complexity level.

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 has 100% coverage with the single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds context by stating the id is returned by subscribe, linking to the subscription creation flow. This adds meaning 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 clearly states the action ('cancel a subscription by id') and the resource ('subscription'). It distinguishes from siblings like subscribe and list_subscriptions by specifying cancellation and deactivation behavior.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions'), which guides when the tool is applicable. It also implies that recent_alerts should be used for historical events after cancellation. However, it does not provide explicit when-not-to-use guidance or alternatives beyond the implication.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: the dual pipeline, return format (verdict, actual value with citation, reasoning), and the tolerance mechanism. No contradictions.

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

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

The description is front-loaded with the most important information (when to use, examples) and is efficient for the complexity of the tool. While it could be slightly tighter (e.g., 'replaces 4–6 sequential calls' is extra), it earns its length by covering purpose, usage, and behavior in a single paragraph.

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

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

Given no output schema, the description compensates by listing the return values (verdict types, actual value with citation, reasoning). Parameters are fully documented. The complexity of the tool (dual pipeline, tolerance, fallback) is well addressed, making the description complete for an AI agent to understand invocation and behavior.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning beyond the schema by explaining tolerance_pct range (0.5–50), default behavior (implied by wording, capped at 5), and a specific use case (set 1–2 for hallucination detection). This elevates it above the baseline of 3.

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

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

The description begins with natural-language examples of when to invoke the tool, states the core function 'natural-language claim verification against authoritative sources', and distinguishes it from siblings by noting it replaces multiple sequential calls. The verb 'verify' and the specific resource 'authoritative sources' 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?

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also details the two pathways (structured SEC EDGAR for company financials, grounded pipeline for any other factual claim) and indicates when to set tolerance_pct (hallucination detection).

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