Codewars

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description complements these by explaining the probing behavior, per-model returns, default model (free), and that _apiKey is passed to Anthropic. It adds behavioral nuance (cost implication for Anthropic, multiple calls per model) that goes beyond annotations.

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

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

The description is a single paragraph of four sentences, each carrying distinct information: core function, model/API key details, return structure, use cases. While dense, it is not wasteful. Could be split into bullet points for clarity, but current form is 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 no output schema, the description adequately explains the return structure (per-model {score, confidence, signals, raw_response} + combined view). It covers all parameters, default behavior, and optionality. Minor omission: no explanation of what score 0-100 means (higher better), but overall complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds meaningful defaults ('Workers AI Llama-3.3-70b (free)') and explains the role of _apiKey and context. It clarifies that models array can be omitted to default workers-ai, and that context disambiguates entities. This enriches the parameter understanding.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb and resource, and the function is distinct from sibling tools like ask_pipeworx (general Q&A) or compare_entities (comparative analysis).

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

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

The description includes explicit use-case guidance: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies the tool is for visibility checks rather than general queries, but does not explicitly exclude scenarios or name alternative tools. Context is clear enough.

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. The description adds valuable context: routing across many tools, auto-filling arguments, returning stable citation URIs, and being one fast call that works on every tier. This goes well beyond the annotations and explains internal 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 lengthy but every sentence earns its place: it is front-loaded with the critical preference signal, includes trigger phrases, examples, default status, and explicit alternatives. No fluff or redundancy despite the length.

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

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

For a complex meta-tool with no output schema, the description fully covers what it does, when to use it, what it returns (structured answer with citations), and when to step up to alternatives. Even addresses breaking-news handling. No major gaps remain.

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% and already explains the 'question' parameter and its aliases clearly. The description provides illustrative examples but no additional parameter semantics beyond the schema. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool's function: routing questions to 5,529 tools across 1,455 verified sources and returning structured answers with citation URIs. It uses a specific verb ('routes', 'returns') and explicitly differentiates it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Offers explicit when-to-use guidance with trigger phrases ('what is', 'look up', 'find'), domain examples (SEC filings, FDA data, etc.), and clear alternatives: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions. Also states 'START HERE for most questions'.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds substantial context: it is experimental, may have active routing candidates, currently matches ask_pipeworx exactly, and is a full working router (no fallback). This fully discloses its behavior and current state.

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 verbose but every sentence carries important information: beta status, equivalence to ask_pipeworx, current candidate state, usage guidance, and clarification that it's a full router. It is front-loaded and structured well, though slightly longer than strictly necessary.

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 natural language router: it explains the experimental nature, current snapshot, and that it works exactly like ask_pipeworx. It doesn't explicitly describe the return format, but referencing the same response shape as ask_pipeworx is sufficient given the sibling context. It covers all necessary operational aspects.

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 covers all parameters with descriptions of aliases for 'question' (100% coverage). The description only says 'same arguments' without adding additional meaning or examples beyond the schema. Baseline of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same tool set and response shape. It explicitly names the sibling tool (ask_pipeworx) and differentiates itself as the experimental edge.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. It provides both a when-to-use condition and the alternative (ask_pipeworx), falling within the top tier for usage guidance.

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

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

Beyond annotations (read-only, open-world), it discloses the exact success and refusal response shapes, including enumerated `refusal_reason` values. It also reveals the cost tradeoff (one extra LLM call) and the grounded extraction ('using ONLY what the tool result contains'), providing rich behavioral context.

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

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

Front-loaded with the core purpose, then logically follows with mechanism, return contract, usage guidance, and cost tradeoff. Each sentence carries distinct information without repetition, keeping it dense but 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?

With no output schema, the description fully specifies the return object and refusal reasons, covering what an agent needs to interpret results. Combined with clear schema and annotations, no critical gaps remain for a tool of moderate complexity with multiple aliases and refusal paths.

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

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

Input schema covers 100% of parameters with clear aliases for `question`, so the description adds no parameter details. Baseline 3; the schema already documents that all six parameters are equivalent to a natural-language question.

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,' clearly stating a specific mode distinct from the sibling `ask_pipeworx`. It describes the extraction process and return format, making the tool's function concrete and differentiating it from alternatives.

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 an answer will be quoted, cited, or acted on, and the agent must not invent facts' with domain examples. Also gives an exclusion: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups,' which is direct alternative guidance.

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

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

The description thoroughly discloses behavior: it resolves, classifies, fans out, returns evidence, and details response shapes. It explains safety measures (low-confidence short-circuit, closed market handling), blocking behavior, and resolution rules. No contradiction with annotations (readOnly, idempotent); all described behaviors are read-only and consistent.

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

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

The description is verbose but well-structured with clear sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Every sentence adds value, but the length may be slightly excessive for an AI agent. Still, it maintains readability and focus.

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 all aspects: input, processing (classification, fan-out), output structure (result.market, analysis, evidence), edge cases (low-confidence, closed markets, wide spreads), and risks (resolution-rule risk). Without an output schema, it fully explains return values and behaviors, making it self-contained.

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

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

Schema coverage is 100%, but the description adds significant value by explaining input formats (slug, URL, question text) and detailing the effect of 'depth' and 'include_raw' parameters with examples. It goes beyond the schema to clarify usage and outcomes.

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: researching a Polymarket bet by pulling Pipeworx data. It provides specific use cases ('should I bet on X') and input formats (slug, URL, question text). The tool is well-distinguished from siblings by focusing on single bet research with data fan-out.

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

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

Explicit usage guidance is given: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z'. It also covers when results are unreliable (low-confidence matches, closed markets, wide spreads) and warns about resolution-rule risk, providing clear when-to-use and when-to-be-cautious.

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), description discloses data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format including citation URIs.

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

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

Front-loaded with common query patterns. Every sentence adds value—no filler. Efficiently packs usage guidelines, parameter behavior, output format, and business logic into a compact 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?

Despite having only 2 parameters and no output schema, description covers expected return (paired data + citation URIs), sorting, and data freshness. No gaps for a comparison tool. Contradictions: none.

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 semantic meaning: explains type enum with examples, values parameter with tickers/CIKs for companies and drug names, constraints (min 2, max 5), and what data each type retrieves.

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 verbs (compare, rank, head-to-head) and clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It distinguishes itself from sibling tools like entity_profile (single entity) and deep_research (more thorough analysis).

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Gives clear context for when to use (comparing entities) and specifies type parameter behavior (company vs drug). Provides example queries.

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 extensive context beyond annotations: account requirements, parallel routing to 5,529 tools, return packet structure (verbatim evidence, confidence, source, fetched_at, citations), explicit gaps[], contradictions[], hop field, and semantic excerpting. No contradiction with annotations; instead, it enriches 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 long but information-dense with every sentence earning its place. It front-loads the critical account warning and proceeds logically through functionality, alternatives, and return details. Slightly dense as a wall of text, but appropriate given the tool's complexity.

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

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

With no output schema, the description fully explains return values (findings packet, gaps[], citations, contradictions) and provides expected latency (15-60s, up to 90s for thorough). Covers prerequisites, alternatives, and edge cases, leaving the agent with all necessary context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by elaborating on the depth enum (e.g., 'standard=5... adds a gap-recovery hop' and 'thorough=8... paid') and clarifying that the question parameter supports 'broad/multi-part' queries, going beyond the schema's own description.

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

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

The description clearly states the tool's core function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call.' It explicitly distinguishes itself from open-web search and from single-lookup siblings like ask_pipeworx, making its unique value proposition obvious.

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 and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and even mentions the account prerequisite with a fallback. Also details depth-level tradeoffs.

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, so the description complements by adding that results come with full schemas and are ready to call directly. It also lists covered domains. No contradictions, and the description adds context beyond annotations.

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

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

The description is moderately long but efficiently packs purpose, usage guidance, domain list, and return format into a few sentences. It is front-loaded with the core action. Minor room for shortening, but overall well-structured.

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

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

Despite lacking an output schema, the description thoroughly explains what the tool returns (relevant tool names, descriptions, full schemas with examples) and states that results are directly callable. This is comprehensive for a discovery tool.

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

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

Schema description coverage is 100%, and the description provides examples of aliases ('task, q, description, search') and sample queries. While helpful, the schema already describes each parameter fully, so the description adds limited additional semantics beyond usage 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 'Find tools by describing the data or task' and enumerates numerous domain examples (SEC filings, financials, FDA drugs, etc.), establishing a very specific verb+resource. It distinguishes from sibling tools by positioning itself as a meta-discovery tool, not a domain-specific tool.

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

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

The description explicitly instructs 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance. It implicitly conveys when not to use (when the target tool is already known) and does not require alternative naming since it is the entry point.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds valuable details: it fans out across multiple sources, returns specific fields like fundamentals sorted by period_end, mentions the USPTO API sunset with soft-fail, and describes fallback logic. Missing rate limit or latency info but otherwise transparent.

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

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

The description is a single dense paragraph that covers many details, but it is somewhat verbose. While it front-loads example queries, it could be more concise by splitting into shorter sentences or bullet points. No waste, but could be tightened.

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

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

Given the tool's complexity (multiple sources, multiple fields), the description covers the main behaviors, return values, and limitations. It mentions the patent API sunset, fallback, and sorting. Missing details on pagination or result limits beyond filings count, but overall complete for the scope.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it clarifies the 'type' enum currently supports only 'company', and for 'value' it specifies that ticker or CIK are accepted but names are not, with examples. This extra context merits a higher score.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company. It provides concrete natural language examples ('Tell me about X', 'research Acme') and enumerates specific data sources and return fields, distinguishing it from single-information 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?

Explicit guidance is given: 'ALWAYS PREFER over chaining single-pack lookups when the user asks for a holistic view.' It also clarifies when not to use (names not supported) and directs to resolve_entity first. This provides clear context for choosing this tool over alternatives.

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

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

Annotations already convey destructiveHint and idempotentHint. The description adds minor context about clearing sensitive data but doesn't elaborate on behavior 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 concise sentences with no wasted words, front-loading the main action immediately.

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 single-parameter tool with full annotations, the description provides complete context, including usage guidance and sibling tool references.

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 clear description for 'key'. The description doesn't add significant meaning beyond the schema, meeting the baseline.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and distinguishes the tool from its siblings (remember, recall) by specifying it's for deletion.

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

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

Explicitly provides usage conditions ('when context is stale, the task is done, or you want to clear sensitive data') and references related tools, helping the agent decide when to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, fully establishing the tool's behavioral safety profile. The description adds that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format,' which provides context but does not significantly extend beyond annotations.

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

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

The description is a single paragraph of three sentences, front-loading the main purpose. It is concise and well-structured, though it could be slightly tighter without losing clarity.

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

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

Given the tool has no output schema, the description adequately explains the output ('single text blob ready to drop at site-root/llms.txt' and notes the standard llms.txt markdown format). For this simple tool, all necessary context is provided.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (url and max_links) with descriptions. The tool description does not repeat parameter details, which is appropriate. It adds no additional semantic nuance beyond what the schema provides, earning the baseline score.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, describing the process and output. It is specific and distinguishes from sibling tools by focusing on llms.txt generation.

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

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

The description includes explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). It does not state when not to use, but the use cases are clear and cover common scenarios.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context by specifying the return value structure (name, rank, tags, etc.) and the input format (ID or slug). 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 a single, well-structured sentence that front-loads the action and efficiently conveys the purpose and return fields. No unnecessary 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 (one parameter, output schema exists, rich annotations), the description is complete. It covers the identifier method and the key return fields, allowing an agent to correctly select and 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?

Schema description coverage is 0%, and the single parameter 'id_or_slug' lacks schema-level description. The description adds minimal meaning by stating 'by ID or slug', but does not clarify format, examples beyond schema examples, or constraints. More detail would be beneficial.

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 'Fetch', the resource 'single Codewars kata', and the identifier method 'by ID or slug'. It also lists the return fields, making it easy to understand what the tool does. Compared to sibling tools, none are similar, so it is well-distinguished.

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 does not explicitly state when to use this tool versus alternatives. However, since there are no sibling tools with similar functionality, usage is implicitly implied for retrieving kata details. No exclusions or alternative suggestions are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it returns specific fields (id, type, params, etc.) and implies default filtering to active subscriptions, which is consistent and adds behavioral context.

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

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

Two sentences: the first clearly states purpose and return fields, the second gives usage guidance. No extraneous words, 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 list tool with readOnlyHint and idempotentHint annotations, the description sufficiently states purpose, return fields, and usage context. No output schema is needed given the listed 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?

Schema coverage is 100% for the single parameter include_inactive. The description does not add any meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description states 'List the caller's active subscriptions.' This is a specific verb (List) and resource (subscriptions), and distinguishes 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?

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

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

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

With all annotations set to false, the description carries the full burden and does so thoroughly. It discloses the claim_token return behavior, the read-later flow, rate limiting (5 per identifier per day), cost implications (free, no quota), and human processing cadence. No contradiction with annotations.

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

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

The description is long but justifiably so given the tool's complexity. It front-loads the primary purpose and critical usage constraints. The motivational sentence about roadmap/digests is a slight extra, but the overall structure remains clear and mostly 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?

Despite having no output schema and no required parameters, the description fully covers the non-trivial aspects: feedback types, scoping exclusions, message format guidance, claim_token lifecycle, and rate limit. It provides enough context for an agent to invoke the tool correctly in all documented scenarios.

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

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

Schema coverage is 100% with rich parameter descriptions, but the description adds meaningful usage semantics beyond the schema: the message should not contain the end-user's prompt, context should reference Pipeworx tools/packs, and claim_token is used to read earlier report status. This clearly enhances parameter understanding.

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

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

The description clearly states this tool sends feedback to the Pipeworx team about broken, missing, or unexpectedly good things. It uses a specific verb+resource pattern ('Tell the Pipeworx team...') and is clearly distinct from sibling research/visibility tools as the feedback channel.

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

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

Provides explicit when-to-use guidance for bug, feature/data_gap, and praise scenarios. It also gives a strong when-not-to-use exclusion: feedback for tools from other MCP servers should be filed elsewhere, not here. Additional guidance about describing issues in terms of Pipeworx tools/packs further disambiguates 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?

Description adds value beyond annotations by revealing derived from CF analytics-engine, no PII, and cached 5min-1h. Annotations already declare readOnly, idempotent, non-destructive; no contradictions.

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

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

Well-structured: first sentence summarizes output, then bulleted use cases, then technical details. Every sentence earns its place 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?

Completes the lack of output schema by describing return fields (top tools, top packs, total call volume). Covers data source, privacy, caching, and parameter behavior fully.

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

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

Schema description coverage is 100% with clear enum and description. Description elaborates on trade-offs between short and long windows, adding meaning 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 uses specific verb 'returns' and clearly identifies resource: top tools, top packs, and total call volume. Distinguishes from siblings like discover_tools or ask_pipeworx by focusing on popularity trends.

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 (hot data sources, canonical tool confirmation, alignment checking). Does not mention when to avoid, but the context is sufficient for an agent to decide appropriateness.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details such as the semantic anchor (Jaccard similarity), partition filter, fill check logic, and the fact that results may be null. 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 very long and contains many details that could be organized better (e.g., separate sections for modes, fill check). While front-loaded with purpose, it lacks conciseness and structure. Every sentence adds value, but the length could be reduced.

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

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

Given the complexity of the tool (multiple modes, output structure, fill check) and the absence of an output schema, the description is remarkably complete. It covers input parameters, response format, edge cases (placeholder slugs, low similarity), and references the fill risk tool for custom sizing.

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 event and topic. The description adds value by explaining that event accepts slugs and URLs, and topic accepts seed questions. It also specifies the behavior for each parameter mode, which goes beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by specifying the unique arbitrage detection methodology.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific markets, topic for cross-event scanning. It also explains the fill check and advises against trading if realizable edge ≤ 0. However, it does not explicitly compare with alternatives like polymarket_fill_risk or polymarket_edges.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: caching at KV level for 1 hour, detailed model families and their calculations, Fed bets excluded from ranking, and diagnostics in the response. No contradiction with annotations.

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

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

The description is long but well-structured: starts with high-level purpose, then segments, response fields, knobs, and diagnostics. It is front-loaded with the purpose. While verbose, every section adds value for this complex tool.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics), caching behavior, and parameter interactions. It covers purpose, usage, parameters, output, and edge cases like Fed bets. Very 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?

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond schema: e.g., slippage_pp explains zero fees but realistic bid/ask; min_partition_leg_kelly explains why min_kelly doesn't apply. The description enriches parameter understanding.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, using a distinct set of model families. This specific verb+resource combo distinguishes it from siblings like polymarket_arbitrage and polymarket_edge_tracker.

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

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

The description explicitly states the tool is built for 'what should I bet on today' and that agents can discover opportunities without paging hundreds of markets. It implies a discovery use case and mentions tradeable-edge knobs, but does not explicitly state when not to use it or compare to 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. The description adds valuable behavioral context: it uses daily closes (not intraday), history is bounded by 60-day TTL, data gaps exist when no scan, and the response structure includes tracked, expired, and snapshot_dates arrays.

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 and includes detailed response structure, which is necessary due to missing output schema. However, it is somewhat verbose and could be more concise by separating response structure into an output schema.

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

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

Given the absence of an output schema, the description adequately explains the response arrays (tracked, expired, snapshot_dates) and limitations. It covers the key fields and data behavior, though it could be more structured.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds minor context (default, max, clamp) but does not significantly extend beyond what the schema provides.

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

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

The description clearly states that the tool tracks edge persistence and decay from daily snapshots, distinguishing it from sibling tools like polymarket_edges. It specifies the core question it answers and differentiates between a fresh wide edge and an old wide edge.

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

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

The description implies usage context by explaining the difference between fresh and old edges, but it does not explicitly state when not to use this tool or mention alternatives beyond the implicit contrast with polymarket_edges.

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=false, so the bar is lower. The description adds behavioral context: walks the order-book ladder, returns verdict (clean|degraded|cannot_fill), and warns about forced directional risk in basket mode. 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 well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and uses bold for key terms. Every sentence adds essential information, though minor trimming could improve conciseness. No fluff.

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

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

No output schema, so description must cover return values. It does: lists fields like top_of_book, vwap_fill_price, slippage_pp, verdict for single-market, and theoretical_sum, realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk for basket. Given the complexity (4 params, dual modes), the description is nearly 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% (baseline 3). Description adds meaning: explains `market` vs `event` for modes, `side` default behavior for basket, and `size_usd` interpretation differences between single-market (max spend/target proceeds) and basket (settlement notional). This adds value beyond the schema descriptions.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and positions itself as a prerequisite before using sibling tools like polymarket_arbitrage. The verb-resource pairing is specific and unambiguous.

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

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

Explicitly requires one of `market` or `event`. Provides clear guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Explains consequences of not using it (partial fills convert arb to directional position), giving strong when-to-use and why.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. The description adds extensive context: compatibility_warning cases, temporal alignment, skipped cross types/subtypes, and response 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?

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and is front-loaded. However, it is somewhat verbose and could be shortened without losing key 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 tool's complexity and lack of output schema, the description fully covers input modes, output fields, safety warnings, and edge cases. It is comprehensive for the agent to understand behavior and return values.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema by explaining the two modes, how topic shortcuts work, and the override behavior. Examples in schema further clarify.

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 computes cross-venue spread between Kalshi and Polymarket. It explains two modes (topic shortcuts and explicit tickers) and distinguishes from sibling tools like polymarket_arbitrage.

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

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

The description explains when to use the tool (comparing prices across venues) and warns that real spreads are rarer than the macro list suggests. It could be more explicit about when not to use, but the safety fields offer clear guidance on meaningless spreads.

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. The description adds value by explaining the behavior of omitting the key to list all keys and the scope (IP, key hash, account ID). No contradictions.

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

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

Two concise sentences with key information front-loaded. Every sentence adds value: first states core action, second gives examples and context. No waste.

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 retrieval tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and pairing with related tools. It leaves no obvious gaps.

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

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

Schema coverage is 100% with a clear description of the 'key' parameter. The description reinforces that omitting the key lists all keys, which adds practical context beyond the schema. Could mention return format but not necessary given simplicity.

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, distinguishing it from siblings like 'remember' and 'forget'. It specifies the resource (values saved via remember) and the action (retrieve/list).

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 when to use: to look up stored context without re-deriving. It mentions scoping and pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use or provide alternatives beyond the explicit pairings.

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

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

Description reveals a side effect (mark_read:true flags events as read) which contradicts the annotation readOnlyHint: true. According to guidelines, contradiction forces a score of 1.

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

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

Three sentences, front-loaded with purpose, followed by parameter usage and an alternative access method. No wasted words; every sentence serves a clear function.

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

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

Description covers input parameters well, explains output format (source, citation_uri, raw payload), and provides alternative access. Lacks mention of pagination beyond limit, but overall sufficient given tool complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real value: it gives concrete filter examples (e.g., 'sec_8k'), explains the effect of mark_read, and clarifies usage context like polling. This exceeds basic schema info.

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 recent alerts from a subscription feed, specifying the returned fields (source, citation_uri, raw payload). It distinguishes from sibling tools like list_subscriptions and subscribe.

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

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

Provides concrete usage guidance: filtering by type and since, using mark_read to manage read state, mentions polling suitability, and gives an alternative access method. Lacks explicit when-not-to-use but is otherwise strong.

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

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

Adds rich behavioral context beyond annotations: fans out to multiple sources, fallback logic, PatentsView sunset, and return structure. No contradiction with annotations.

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

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

Well-structured with examples first, then mechanics, then parameter details, and differentiator. Slightly lengthy but every sentence adds value.

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

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

Despite no output schema, describes return structure, fallback behavior, and error handling comprehensively for a multi-source tool.

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

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

Schema coverage is 100%, but description adds extra clarifications like 'since' accepts ISO or relative, 'value' is ticker or CIK, and usage advice.

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 is a change feed for a company over a recent window, using examples like 'What's new with X' and explicitly distinguishing from sibling tool 'entity_profile'.

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

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

Provides explicit when-to-use (recent changes) and when-not-to-use ('Use entity_profile instead for static profile'), plus detailed behavior like fallback between GDELT and GNews.

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 and destructiveHint=false. Description adds details about key-value pair scoping, 24-hour retention for anonymous, and persistence for authenticated users, going 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?

Description is a single paragraph of 4 sentences, all highly informative. No redundant or vague sentences; each 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 all needed context: purpose, usage conditions, scoping, persistence rules, and pairings with sibling tools. No output schema needed for a simple write tool.

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

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

Schema already provides 100% coverage with descriptions for both parameters. Description adds value by explaining the key-value concept and providing example keys ('subject_property', 'target_ticker').

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 'Save data the agent will need to reuse later' which is a specific verb+resource. It distinguishes from siblings like recall and forget by explaining the storage purpose.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and references alternatives (recall, forget). Also clarifies session vs. persistent memory for different user types.

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

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

Despite having strong annotations (read-only, idempotent), the description adds substantial behavioral context: cascading internal lookups, graceful degradation when external sources are unavailable, explicit reporting of unresolved identifiers, and source attribution. This goes far beyond annotation-provided information.

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

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

The description is long but well-structured, opening with query examples and a clear directive, then detailing each supported type. Every sentence carries meaningful information, though it could be tightened without losing 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?

With no output schema, the description compensates by enumerating return values, unresolved handling, fallback behavior, and source attribution. It thoroughly covers both entity types and addresses the tool's complexity 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?

Although the schema documents both parameters at 100% coverage, the description adds richer semantics: accepted input formats (ticker, CIK, name for company; brand/generic for drug) and output fields such as CIK, LEI, FIGI, RxCUI, and ownership relationships. This elevates it beyond 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 clearly states the tool's purpose: resolving user-spoken names to canonical identifiers required by other tools. It opens with concrete query examples and distinguishes itself from siblings by explicitly stating 'Use FIRST whenever you have a name but need an ID.' This is a specific verb+resource+scope.

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

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

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID' and it notes that the tool replaces 2-3 manual lookups. However, it lacks when-not-to-use guidance and does not compare against specific sibling alternatives (e.g., entity_profile), so it falls short of a 5.

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

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

Description adds significant context beyond annotations (which declare readOnly, idempotent, non-destructive). It explains it probes each entity with ai_visibility_check, ranks by score, and returns ranked list. 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?

Three sentences, front-loaded with main purpose. No wasted words. Clearly structured: what it does, how it works, when to use, and return format.

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

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

No output schema, but description covers return format (ranked list with score, confidence, signal density). With annotations providing safety profile, this is complete for an agent to use effectively.

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

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

Schema coverage is 100% (baseline 3). Description adds value by noting the first entity is treated as subject for narrative, which is not in schema. It also explains the overall purpose of the parameters.

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

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

Description clearly states verb 'Compare' and resource 'AI visibility across multiple entities'. It distinguishes from sibling 'ai_visibility_check' (single entity) and 'compare_entities' (generic comparison) by specifying it probes AI presence and ranks entities.

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 usage context ('competitive AI-marketing audits') and an example question. However, it does not explicitly state when not to use or contrast with alternatives like ai_visibility_check for single probes.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds significant context: partial failure behavior (sources_failed list), timing caveat (5-30s first measurement), and graceful degradation. No contradiction with annotations.

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

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

Description is well-structured: front-loaded with composite nature and purpose, followed by usage, return fields, ecosystem limitation, and failure behavior. Every sentence adds value with zero waste.

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

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

Given no output schema, description explains return fields (summary, advisories, links, alternatives) and failure modes. It fully covers the tool's behavior for a composite multi-source call.

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. Description does not add meaning beyond schema (e.g., default version behavior is already in schema). 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?

Description clearly states it is a composite check for npm packages using deps.dev and bundlephobia, with specific verb 'scan dependency' and resource 'npm package'. It distinguishes from sibling tools like scan_competitor_ai_presence by scope (npm only) and purpose (safety/popularity/size).

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 asking 'is X safe/popular/small' or 'what does adding lodash cost me'. Also provides exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving a clear alternative.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds technical details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs truncated and flagged)' and mentions offset for verification.

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

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

Single paragraph front-loads core purpose. Includes necessary details without redundancy; could slightly tighten the technical sentence 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?

Given tool complexity (semantic search, offsets, pairing), description covers purpose, usage, technical behavior, and output format ('top-N passages with character offsets and similarity scores'). No output schema, but description compensates.

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

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

Schema coverage is 100%, baseline 3. Description adds context for all parameters (e.g., 'natural-language query' with examples, 'max ~200K chars' for text, limit 1-20) and explains embedding mechanics, adding value beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from sibling tool ask_pipeworx_grounded by explaining the pairing and use case.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and provides an alternative strategy involving ask_pipeworx_grounded.

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

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

The description goes well beyond the annotations. It details the mutation behavior (creating a subscription), the requirement for a specific account type, return value, delivery channels with constraints (phone verification, SMS cap, webhook auto-disable), and supported event types. This provides rich behavioral context.

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

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

The description is well-structured with clear sections for type and delivery, and the first sentence effectively front-loads the purpose. While it is somewhat lengthy, every sentence contributes necessary information. Minor redundancy 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 the tool's complexity (3 parameters, nested objects, no output schema), the description covers most aspects: account requirements, type-specific params, delivery options with constraints. However, it does not clarify idempotency behavior (though annotations indicate idempotentHint=true) or the exact structure of the returned subscription id. Still, it is quite thorough.

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

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

Although the input schema already has 100% description coverage, the description adds significant value by providing concrete examples for each subscription type (e.g., 'sec_8k: items:["5.02"] = officer change') and detailed explanations of delivery options including webhook signature verification. This greatly enhances understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns the subscription id. It specifies the resource (live-data event stream) and the verb (create). However, it does not explicitly differentiate from sibling tools like 'list_subscriptions' or 'unsubscribe', though the purpose is distinct enough.

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

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

The description mentions the requirement for a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions, implying appropriate use cases. However, it lacks explicit when-to-use vs. when-not-to-use guidance and does not mention alternatives among sibling tools.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds value by explaining the exact output format (category-bucketed example questions with tool+argument shapes) and the behavior when called with no arguments vs. with a topic. This goes beyond the annotations to give a clear picture of what happens.

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, starting with common user queries, then explaining the output, then parameter usage. Each sentence serves a purpose, but it is somewhat verbose. Front-loading effectively communicates the tool's primary use case.

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 that there is no output schema, the description adequately explains the return type (category-bucketed example questions with tool shapes). It covers the parameter and usage context thoroughly. A small gap is the lack of mention of potential limitations or empty results, but overall it is complete for the tool's simplicity.

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

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

The schema describes the 'topic' parameter with a list of options. The description enriches this by providing concrete examples of focus areas (finance, pharma, etc.) and stating that omitting it yields a cross-category spread. This adds practical context beyond the schema's description, though the schema coverage is already 100%.

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

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

The description clearly states that this tool is the onboarding entry point for an agent that just connected, providing example questions and tool usage. It uses specific verbs ('returns category-bucketed example questions') and distinguishes itself from siblings by positioning it as the first tool to use when the agent doesn't know what to ask.

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 this FIRST when you do not yet know what Pipeworx can do for you') and how to use it (with no arguments or with a topic focus). It also mentions related meta-tools but does not exhaustively list all sibling alternatives or provide 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 adds significant behavioral detail beyond annotations: it explains that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. Annotations only provide idempotentHint and destructiveHint, so this context is valuable.

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

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

Two sentences with no redundant information. Every sentence serves a purpose: the first states the action and ownership constraint, the second explains the behavioral nuance.

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 mutation tool with one parameter and no output schema, the description fully covers purpose, ownership, the deactivation behavior, and the impact on historical data. It also connects to the related tool recent_alerts.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that the subscription id is 'returned by subscribe,' which clarifies the parameter's origin. This 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 'Cancel a subscription by id,' providing a specific verb and resource. It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), which provides clear guidance on when to use the tool. It does not explicitly name alternatives but implies not to use for others' subscriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, so the description need not repeat safety. It adds context by listing returned fields and stating 'public profile', but does not disclose potential errors, rate limits, or whether authentication is required (though likely not needed for public profile).

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, highly concise, no redundancy. Lists key output fields efficiently. Could be slightly improved with bullet points, but structure is adequate.

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 output schema likely defines return structure, the description covers the essential purpose and output scope. It does not mention error conditions or rate limits, but for a simple public fetch with full annotations, it is reasonably complete.

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

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

Schema description coverage is 0%, so the description should compensate for the undocumented 'username' parameter. However, it only says 'by username', offering no format, constraints, or examples beyond the schema's provided example.

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

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

Description clearly states the verb 'Fetch' and specific resource 'Codewars user's public profile', listing key fields (honor, clan, rank). This distinguishes it from sibling tools like 'kata' (fetch kata) or 'user_completed' (completed katas).

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

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

The description implies usage (to get user profile) but does not explicitly state when to use versus alternatives, nor does it provide when-not-to-use guidance. For a simple tool, this is adequate but lacks differentiation from siblings like 'user_authored' or 'resolve_entity'.

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 safe, read-only, idempotent behavior. The description adds that it returns specific fields and multiple kata, but does not contradict annotations. Minimal added behavioral context.

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

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

Single sentence, front-loaded with key information, no wasted words. Efficiently conveys purpose and output.

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

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

With a complete output schema (has-output-schema=true), a single required parameter, and thorough annotations, the description adequately explains the tool's function. The listed returned fields complement the 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 0% with no parameter descriptions in schema. The description only implies the username parameter through context ('by a Codewars username'), adding minimal detail beyond the schema's property name and required flag.

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

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

Description clearly states the verb 'List', resource 'kata authored by a Codewars username', and specifies the returned fields (ID, slug, name, rank, tags, languages). This distinguishes it from sibling tools like user_completed (completed kata) and kata (specific kata details).

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?

Implicitly indicates usage for listing authored kata, but no explicit guidance on when to use versus alternatives (e.g., user_completed for completed kata) or conditions for use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds pagination and return fields, but does not address openWorldHint (results may change) or provide additional 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?

Single sentence, front-loaded with action and resource, 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 output schema, annotations, and sibling tools, the description covers the essential aspects. Missing are details on ordering, page size, or error behavior, but these are not critical for basic usage.

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

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

With 0% schema description coverage, the description compensates partially by mentioning pagination, implying the 'page' parameter controls page number. 'username' is clear. However, no format details or defaults are given.

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

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

Description clearly states the verb 'List', the resource 'completed kata for a username', and distinguishes from siblings like 'user' and 'user_authored'. It also specifies pagination and return fields.

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 does not explicitly state when to use or when not to use this tool versus alternatives. The context implies it's for completed kata, but no guidance on exclusion criteria.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, and the description goes beyond them by detailing the semantics of 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source found). This additional context is critical for correct interpretation of results.

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

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

The description is dense but every sentence earns its place: trigger phrases, architectural distinction, verdict list, evidence format, and caller warnings. It is somewhat long but well-structured and free of 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?

With no output schema, the description fully explains the return values (verdict enum, grounded/structured value with citation, reasoning) and error handling. It covers both claim categories and provides an important warning about 'could_not_verify', making it 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?

Schema coverage is 100%, so the baseline is 3. The description adds significant value by explaining that tolerance_pct overrides the tolerance implied by the claim wording, has a default capped at 5, and is recommended at 1–2 for hallucination detection—details not present in the schema.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with explicit trigger phrases and a distinction from generic Q&A. It also notes that it replaces a multi-step pipeline, making its purpose unambiguous and differentiating it from sibling tools like ask_pipeworx.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides trigger phrases. It also explains the dual-path behavior for financial vs. other claims. It does not name alternative sibling tools, but the usage context is clearly specified.

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