Ai Incident Db

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds the response format (per-model score, confidence, signals, raw_response + combined view) and explains the payment model for Anthropic. No contradictions.

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

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

The description is concise (3 sentences) and well-structured: main action first, then model details, then return format, and finally use cases. No redundant information.

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

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

Given the absence of output schema, the description adequately explains the return structure. All 4 parameters are described in the schema and further contextualized in the description. The use cases and model requirements are clear, making the tool definition complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model (Workers AI Llama-3.3-70b, free) and the _apiKey's purpose (BYO key, direct payment). It also clarifies the context parameter's role in disambiguation.

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

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

The description clearly states the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It distinguishes this tool from siblings like ask_pipeworx or compare_entities by focusing on AI visibility audits.

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

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

Provides clear usage contexts (AI-marketing audits, pre-launch brand checks, competitive monitoring) and notes when to provide an API key for Anthropic. However, it does not explicitly list alternatives or when not to use, but given its unique function, guidance is sufficient.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive. The description adds value by disclosing routing to 5,439 tools across 1,412 sources, argument filling, stable citation URIs, and 'one fast call' behavior. It doesn't mention limitations or edge cases, but the additional context goes beyond the annotation baseline.

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?

Though long, every sentence serves a purpose: opening directive, domain examples, trigger phrases, use cases, escalation paths, and coverage clarifications. The structure flows logically from what to when to alternatives, and is front-loaded with the most important advice.

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 broad scope and no output schema, the description covers all necessary context: purpose, usage, alternatives, examples, and return behavior (structured answer with citation URIs). It also clarifies tier availability and speed, making it a complete guide for selecting and invoking this tool.

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

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

Schema coverage is 100% with alias parameters clearly described. The description enriches semantics by providing concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') and emphasizing natural language input, making it easier to understand what to pass in the 'question' parameter.

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

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

The description clearly states the tool's purpose: answering factual questions by routing to verified sources and returning structured answers with citations. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, and specifies its role as the default entry point.

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

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

Provides explicit usage guidance: 'PREFER OVER WEB SEARCH', 'Use whenever...', and 'START HERE for most questions'. It also names alternatives for when to step up ('for hallucination-resistant... use ask_pipeworx_grounded; for broad/multi-part... use deep_research') and clarifies it already handles breaking news.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral context: it is a live experimental variant whose behavior may change when a candidate routing improvement is under test. It also discloses the current state (no candidate active, so behavior is identical to ask_pipeworx) and the evaluation mechanism (results are compared to the stable router). This goes beyond annotations by explaining the dynamic nature of the tool.

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

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

The description is well-structured and front-loaded with the core identity ('Beta version of ask_pipeworx'), followed by the current status and usage guidance. It is slightly verbose (e.g., the parenthetical retirement date is extra detail), but every sentence contributes meaningful context and there is no fluff. It earns a 4 for being informative without being overly long.

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 schema covers all parameters and annotations cover safety, the description fills the remaining gaps: it explains the beta nature, the current equivalence to the stable router, and the experimental purpose. It does not specify the response shape, but it explicitly says 'same response shape' as ask_pipeworx, which is sufficient in this context. The description is complete enough for an agent to select and invoke the tool correctly.

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

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

The input schema has 100% coverage, with all parameters described, including the 'question' parameter and its five aliases. The description does not add parameter-level semantics beyond what the schema already provides; it merely mentions 'same arguments' as ask_pipeworx, which is redundant. Given the high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool is a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It explicitly distinguishes it from the stable ask_pipeworx by framing it as the 'experimental edge' and notes that when no candidate is active, it matches ask_pipeworx exactly. The verb 'ask' and resource 'pipeworx' are clear, and the purpose (testing routing improvements) is directly stated.

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 tells the user when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also names the alternative (ask_pipeworx) and explains the trade-off (results compared against the stable router). The statement 'Falls back to nothing — this IS a full working router' preempts any concern that this is a stub, making usage guidance unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds substantial context beyond these: the strict extraction behavior, explicit refusal reasons, the reliance only on tool result content, and the cost of one extra LLM call. This gives a complete behavioral picture without contradiction.

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

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

The description is front-loaded with the core purpose and includes valuable details (mechanism, return shape, refusal reasons, usage guidance). It is somewhat long but every sentence contributes meaningful information. It is not as tight as a two-sentence minimal description, but well-structured and free of fluff.

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

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

Given the tool's complexity (routing, extraction, refusal handling), the description is comprehensive: it explains what the tool returns on success and failure, when to use it, cost implications, and it references the sibling alternative. The schema is simple and the description covers everything needed for correct invocation, so no significant 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 coverage is 100%: all six parameters are aliases for 'question' and the schema already states 'Your question in natural language.' The description adds no extra parameter semantics, so baseline 3 is appropriate per the rubric.

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 'hallucination-resistant answer mode for high-stakes reads' with a specific verb ('extracts the answer') and resource. It explicitly distinguishes from the sibling 'ask_pipeworx' by noting it uses the same routing but adds grounded extraction, so the purpose is unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' plus concrete examples. It also states when not to use it: 'prefer ask_pipeworx for casual lookups,' which directly addresses 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, and idempotentHint. The description adds rich behavioral details: how market resolution works, fan-out logic per category, response shapes (market, analysis, evidence), resolver contract (confidence, alternatives), parent event extraction, news fallback mechanisms, safety short-circuits for low confidence/closed markets, wide-spread warnings, and cancellation rule parsing. This goes well beyond the annotations.

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

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

The description is lengthy but well-structured with clear section headers (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK). The core purpose and usage are front-loaded. While some redundancy exists (e.g., repeated mention of closed markets), each section adds necessary detail for such a complex tool, justifying 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?

Given the tool's complexity (3 parameters, no output schema), the description is highly complete. It explains all return value shapes (evidence packet, market-vs-model comparison), error states (low_confidence_match, market_closed_or_inactive), and edge cases (wide spreads, cancellation rules). Without an output schema, the description fully 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 description coverage is 100% (all three parameters have descriptions). The tool description adds extra context: for 'market' it explains accepted formats (slug, URL, question text); for 'depth' it clarifies quick vs thorough; for 'include_raw' it explains when to use true (recompute deltas, post-process). It also provides schema examples and connects parameters to the fan-out behavior.

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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and how (one-call fan-out). It distinguishes itself from sibling research tools by focusing on Polymarket bets with explicit classifier categories and fan-out examples.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides extensive fan-out examples for different bet types. While it doesn't explicitly state when not to use it, the specificity implies alternatives exist for non-betting research, making the guidance clear and actionable.

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 critical behavioral details: it pulls data from SEC EDGAR/XBRL for companies (handling off-calendar fiscal years correctly) and FAERS/FDA for drugs, returns paired data with citation URIs, and sorts results by primary metric so 'largest' reads from the top. No contradictions with annotations.

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

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

The description is dense and informative, front-loading trigger phrases and key behavior, then detailing type-specific logic and output. While every sentence adds value, the length could be slightly reduced for faster parsing (e.g., splitting into bullet points). The structure is clear but could be more concise.

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

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

Given that the tool has only two parameters, no output schema, and annotations already signal safety (readOnly, idempotent), the description covers all necessary context: data sources, output format (paired data + citation URIs), sorting behavior, and efficiency advantage over sequential lookups. No gaps remain for the agent to infer.

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?

Even though the input schema has 100% coverage for parameter descriptions, the description substantially enriches semantics by explaining the data sources and behavior for each 'type' value ('company' pulls revenue/net income/cash/debt; 'drug' pulls FAERS counts), providing examples for 'values' (tickers/CIKs for company, drug names), and noting that fiscal year handling is correct. This goes well beyond the schema's basic enum 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 explicitly states the tool's function: side-by-side comparison of 2-5 entities (companies or drugs) in a single parallel call. It provides multiple example trigger phrases and clearly distinguishes from sequential single-entity lookups by stating 'ALWAYS PREFER over sequential single-pack lookups' and noting it replaces 8-15 sequential lookups.

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

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

The description gives explicit guidance on when to use this tool (e.g., any comparative query like 'compare X and Y', 'rank these companies', 'head to head') and implicitly advises against using slower sequential alternatives. It also explains the 'type' parameter's role and the data sources for each type, ensuring the agent can select the correct tool based on the user's intent.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses account requirements, paid plans, parallel execution, the findings packet structure (gaps[], contradictions[], hop field, citation_uri), semantic excerpting behavior, timing, and that it never invents answers. This is exceptional transparency with no contradiction to 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?

Despite being long, every sentence earns its place: prerequisites are front-loaded, distinctions from alternatives are clear, and technical details are dense but never redundant. The structure uses parentheticals and semicolons effectively to pack high-value information without bloat.

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

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

With no output schema, the description fully describes the expected return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri. It also covers timing and edge cases like empty gaps for off-catalog topics. There is no missing information an agent needs to invoke this tool correctly.

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

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

The schema already covers both parameters comprehensively (100% coverage), including detailed enum descriptions for 'depth' and explanation of 'question'. The description adds contextual meaning beyond the schema by illustrating broad/multi-part questions, the 'standard' gap-recovery behavior, and the 'thorough' paid requirement. It enriches, but doesn't carry the full burden, so a 4 is appropriate.

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

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

The description uses the specific verb 'research' with a clear resource: 'PIPEWORX's 1412 STRUCTURED data sources'. It explicitly states what the tool does and contrasts it with 'NOT open-web search'. It also distinguishes itself from siblings like ask_pipeworx by scope and use case. This is a model of purpose clarity.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and mentions the sign-in requirement with a fallback. It also explains the differences between depth settings. This far exceeds minimal guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining the output includes schemas and curated examples, and that results are ready to call without second lookup.

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

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

Two sentences, front-loaded with purpose. The list of domains is informative but somewhat long. No wasted words; overall concise.

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

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

Despite no output schema, the description fully explains the output format (tool names, descriptions, schemas with examples) and usage context. Adequate for the tool's discovery purpose.

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

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

Schema coverage is 100% with descriptions for all parameters. The description does not add additional meaning beyond what the schema provides, so baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task' and lists specific domains. It distinguishes itself from sibling tools which are for specific tasks, making it the discovery entry point.

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

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

Explicitly says 'Call this FIRST when you have many tools available' and describes when to use (browse, search, look up). Could be more explicit about when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds context on parallel fan-out across multiple sources, specific return fields, and soft-failure for patents, which is valuable 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 well-structured with example queries first, then explanation. It is comprehensive but slightly verbose; could be trimmed slightly 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 complexity (multi-source profile), the description covers all essential aspects: input requirements, output fields, limitations (patents, names), and prioritization guidance. No output schema exists, so the description compensates adequately.

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

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

Schema description coverage is 100% (both parameters described in detail). The description repeats this information without adding new semantic meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description explicitly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It includes example queries and details the return fields, clearly distinguishing it from sibling tools like resolve_entity or chaining individual lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies when not to use it (names not supported, use resolve_entity first), and notes limitations like patents soft-fail.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, so the description doesn't need to restate those. The description adds use-case context ('clear sensitive data') and reinforces the destructive nature, which is consistent with annotations. No contradictions.

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

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

The description is extremely concise with two sentences: the first states the core action, the second provides usage guidelines and mentions related tools. Every sentence earns its place with no wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description provides sufficient context. It covers purpose, usage scenarios, and related tools, making it complete for agent invocation.

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

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

Schema coverage for the single required parameter 'key' is 100%, with a clear description 'Memory key to delete.' The definition adds no additional semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Delete') and the resource ('a previously stored memory by key'). It distinguishes from siblings like 'remember' and 'recall' by focusing on deletion, making the tool's purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember' and 'recall,' implicitly guiding when not to use it (i.e., for storing or retrieving).

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 readOnly, openWorld, idempotent, non-destructive. The description adds value by describing the exact actions (fetches page, extracts info, emits standard format) and output format (text blob for site-root/llms.txt). 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 concise, front-loaded with purpose, and includes all necessary details in just a few sentences without redundancy.

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

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

Given the rich annotations and full schema coverage, the description provides complete context: purpose, input, output, and use cases. No output schema but the description clearly explains the output format.

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

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

Schema has 100% coverage with good descriptions for both parameters (url and max_links). The description adds defaults (max 25, max 50) and clarifies URL type, adding value beyond the schema alone.

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

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

The description clearly states the tool generates a 'production-ready llms.txt file' for a given URL, providing the exact output and use cases. It is distinct from sibling tools, none of which perform this function.

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

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

The description lists three specific use cases (client indexing, own project drafting, competitor auditing), giving clear context for when to use. It does not explicitly state when not to use or name alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds return field details (title, date, etc.) but doesn't reveal further behavioral traits beyond what annotations cover.

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

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

Single sentence, no redundancy, directly conveys core functionality and return data. Front-loaded with key verb and resource.

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 a simple fetch operation with output schema present, description sufficiently covers return values and purpose. No gaps for this 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 covers 100% of parameters with description 'Numeric AIID incident id'. Description adds no additional semantic detail 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?

Clearly states verb 'Fetch' and resource 'AI Incident Database record by numeric incident_id'. Distinguishes from siblings like search_incidents by indicating it retrieves a single full record.

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?

Implies usage for fetching a specific incident by ID, but no explicit guidance on when to use versus alternatives like search_incidents. Lacks when-not-to-use or context about prerequisites.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds no further behavioral details (e.g., pagination, sorting order, data limits) beyond stating it returns 'most recently added incidents'. This adds minimal value beyond the annotations.

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

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

The description is a short phrase, concise but not a full sentence. It is front-loaded but could be more structured (e.g., 'Lists the most recently added incidents.'). It lacks brevity without sacrificing clarity, but 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 simple tool (one optional parameter, output schema exists), the description provides baseline understanding. However, it does not specify default ordering, whether all incidents are included, or how 'recent' is defined (e.g., time frame). Completeness is adequate but not 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?

The schema covers the single 'limit' parameter well, with a clear description of range and default. The tool description does not add additional meaning, so the baseline score of 3 is appropriate. No extra context is provided about how the limit affects results.

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 'Most recently added incidents' clearly identifies the tool as listing recent incidents. The title 'List Recent' supports this. While it distinguishes from siblings like 'search_incidents' and 'get_incident', it could be more explicit about differentiating from other list tools (e.g., 'list_subscriptions').

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

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

No guidance is provided on when to use this tool versus alternatives like 'search_incidents' or 'recent_alerts'. The description does not specify context, prerequisites, or when not to use it, leaving the agent to infer usage.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds behavioral context by listing specific return fields (id, type, params, created_at, last_fired_at, fire_count), which goes beyond what annotations provide. No contradiction.

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

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

Two sentences, front-loaded with the main purpose. Every word adds value. No unnecessary repetition or fluff.

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

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

No output schema, but the description explicitly lists the return fields. The single parameter is fully described in the schema. For a simple list tool with rich annotations, the description is complete enough to guide correct invocation.

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

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

Schema has one parameter (include_inactive) with a description, achieving 100% coverage. The tool description does not add additional meaning beyond the 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 'List the caller's active subscriptions', specifying the resource (subscriptions), verb (List), and scope (caller's active). It distinguishes from sibling tools like subscribe and unsubscribe which have different purposes.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use the tool. Does not mention when not to use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. Description adds minimal behavioral context beyond stating the purpose (classifying incidents). No contradiction with annotations.

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

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

Single sentence, highly concise, front-loads key information (purpose and examples). 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?

Tool is simple with no parameters and an output schema. Description adequately covers purpose and scope. Could briefly mention that it returns a list, but output schema already exists, so not required.

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

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

No parameters exist (schema coverage 100% vacuously). Description adds meaning by specifying the kind of taxonomies (classification-related), but no parameter-level detail needed. Baseline 4 for zero-parameter tools.

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 explicitly states that the tool lists taxonomies used for incident classification, with specific examples (CSET-AIID, GMF, RAIC). This clearly distinguishes it from sibling tools like 'search_incidents' or 'get_incident'.

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

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

Description implies usage context (when needing to know available taxonomies) but provides no explicit guidance on when to use this versus alternatives or any exclusions. No mention of prerequisites or when not to 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 are all false, so the description carries the burden of behavioral disclosure. It explicitly mentions rate limiting ('Rate-limited to 5 per identifier per day'), that it is free and doesn't count against quota, that the team reads digests daily, and instructs users not to paste end-user prompts. 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 longer than average but every sentence earns its place: purpose, triggers, exclusions, formatting guidance, and operational details. It is front-loaded with the core purpose and flows logically, though it could be slightly tightened without losing essential scope.

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 provides complete context for a feedback tool: what it does, when to use, when not to, rate limits, quota impact, and even roadmap influence. No output schema exists but returning a confirmation is standard and not needed to be documented. The exclusions and alternative routing make it fully 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%, with each parameter well-described. The description adds extra meaning beyond the schema by advising how to frame the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by connecting the context field to tools/packs. This supplemental guidance justifies above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It names the specific resource (Pipeworx team) and distinguishes from all sibling tools by being the only feedback channel, explicitly enumerating supported feedback types (bug, feature/data_gap, praise).

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 triggers: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead,' plus guidance for identifying Pipeworx 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h). No contradictions.

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

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

The description is concise with three compact paragraphs. It leads with the core purpose, bullet-points use cases, and ends with technical details. Every sentence adds value, no fluff.

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

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

Given the simple tool (one optional param, read-only), the description is complete: it explains output components, window semantics, caching, data source, and privacy. No output schema, but the description sufficiently covers expected returns.

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

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

The schema has one parameter 'window' with enum and description. The tool description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This extra meaning helps the agent choose appropriately.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window'. It specifies the window options and directly addresses common use cases, distinguishing it from sibling tools like 'discover_tools' by focusing on real-time trending data.

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

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

Three specific use cases are listed (discovering hot data sources, confirming canonical tools, aligning with agent needs). However, it does not explicitly state when not to use this tool versus similar siblings, though the purpose 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?

The description discloses extensive behavioral details beyond annotations: mode behavior, semantic anchor with Jaccard similarity, partition filter, fill check with live CLOB depth, and response structure. 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 long but well-structured with clear mode separation and organized details. Every sentence adds value, though some minor redundancy could be trimmed. Front-loaded with key purpose.

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

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

Given the tool's complexity (multiple modes, edge cases, fill check), the description is exceptionally complete. It covers all necessary aspects: how to use, what to expect, limitations, and integration with sibling tools. No output schema but describes response fields adequately.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value by explaining parameter usage context, recommended use cases, and operational details like event slug format and topic search behavior.

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 tool clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from siblings like polymarket_fill_risk by specifying its unique approach and includes sibling tool references.

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

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

It provides explicit guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event scan) and mentions when not to trade (realizable_edge_pp ≤ 0). References sibling tool for custom sizing.

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

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

The description goes into extensive detail about the internal models, caching behavior (1h KV cache), diagnostic output, and tradeable-edge knobs. This provides significant context beyond the annotations (readOnlyHint, idempotentHint), which are already present. No contradictions.

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

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

The description is lengthy but well-structured, starting with the main purpose, then breaking down segments, knobs, and response format. Every sentence adds necessary detail for a complex tool, so it earns its length. Slight reduction possible, but not at the cost of 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 complexity (9 parameters, no output schema), the description covers all aspects: input knobs, model families, response structure including diagnostics, and even caveats like Fed bets exclusions. It is highly complete and leaves no major gaps for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the role of parameters like min_liquidity and max_spread_pp as 'Tradeable-edge knobs' and describing their effect on opportunity feasibility, providing context that aids in selection.

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: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings by specifying 'Pipeworx data' and the three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), which are unique to this 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 says 'Built for "what should I bet on today"' and describes the three segments, which implies appropriate use cases. However, it does not explicitly state when not to use this tool or compare directly with siblings like polymarket_arbitrage or polymarket_edge_tracker, 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: response structure (tracked, expired, snapshot_dates), limits on history depth (60-day TTL), and that decay numbers are from daily closes, not intraday.

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-organized: starts with purpose, then response format, then limits. While dense, it remains efficient and front-loaded. 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?

No output schema exists, but the description thoroughly explains the response structure (tracked with time-series, trend, decay; expired with lifespan; snapshot_dates). This compensates for the missing output schema and makes the tool fully understandable.

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

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

Both parameters (days, window) are documented in the schema (100% coverage). The description adds defaults and clarifies semantics: days default 14, max 30; window as snapshot family. This adds value beyond the schema.

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

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

The description clearly states it provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' This distinguishes it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implies when to use this tool by contrasting fresh vs. old edges, but does not explicitly list alternatives or state when not to use it. It gives context but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral context beyond these: it explains that the tool checks order book depth, returns verdicts (clean/degraded/cannot_fill), and identifies forced directional risk. 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 thorough but fairly long (several paragraphs). It is front-loaded with the core purpose, and the structure is logical, but some details could be condensed without losing meaning. It earns its keep but could be more concise.

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

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

Given no output schema, the description compensates by listing return fields for both modes (e.g., top_of_book, verdict, capture_ratio, forced_directional_risk) and explains the risk of partial fills. It provides enough context for an agent to understand what the tool outputs and why it is needed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: it clarifies the difference between single-market and basket modes, explains default side logic, and details how size_usd is interpreted (spend vs target proceeds vs settlement notional). This goes well 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before those.

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 the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (risk of partial fills creating unhedged positions). However, it does not list all possible alternatives or explicitly state when not to use it.

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

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

Annotations declare readOnly/indempotent/non-destructive; the description adds rich detail: safety fields (compatibility_warning with two cases), temporal_alignment, skipped counters, and response structure. No contradiction with annotations.

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

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

Well-structured and front-loaded with the core idea, but somewhat lengthy with repetition (e.g., 'pre-mapped ≠ tradeable' appears twice). Could be trimmed slightly, but still effective.

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 the description fully explains the response: each venue's prices, spread values, and all safety fields. Covers compatibility, temporal alignment, and skip counters. Complete for a tool with good annotations.

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

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

Schema coverage is 100% with descriptions; the description adds valuable context beyond schema, such as the list of topic shortcuts, their semantics, and the override behavior for explicit tickers. Enhances usability.

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

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

The description explicitly states the tool computes cross-venue spread between Kalshi and Polymarket, with clear verb+resource ('Cross-venue spread'). It distinguishes from siblings like polymarket_arbitrage by focusing on same-question spread across venues.

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?

Two modes are clearly explained (topic shortcuts vs explicit tickers), with guidance on when compatibility warnings appear and when spreads are not meaningful. It warns that real spreads are rarer than the shortcut list suggests, preventing misuse.

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, so the safety profile is clear. The description adds valuable context about scoping (anonymous IP, key hash, account ID) and the behavior when key is omitted. It doesn't cover edge cases like missing keys, but overall adds good transparency.

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 action, no redundant words. Every sentence adds value: purpose, usage, scoping, and complement tools. Excellent conciseness.

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

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

For a simple tool with one optional parameter, good annotations, and no output schema, the description fully explains behavior, usage, scoping, and relationships. No gaps.

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

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

With 100% schema coverage, the parameter is already well-described. The description adds meaning by explaining the key is from 'remember', the listing behavior when omitted, and the relationship with sibling tools. This goes beyond the schema's basic 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 retrieves a value saved via 'remember' or lists all keys when no argument is given. It uses specific verbs ('retrieve', 'list') and identifies the resource (saved values/keys). Examples in the input schema reinforce this.

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 to use for looking up previously stored context without re-deriving it, and mentions pairing with 'remember' and 'forget'. It gives scoping info but does not explicitly state when not to use it.

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

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

The description states that mark_read:true 'flag[s] returned events read', which is a state mutation. This directly contradicts the annotation readOnlyHint=true. The description does not reconcile or warn about this side effect, leading to a severe transparency issue.

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

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

The description is compact (3-4 sentences) and well-organized: purpose, return fields, filtering, mark_read behavior, and alternative access method. 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 annotations and full schema coverage, the description covers purpose, parameters, and usage context. However, it omits details on pagination, rate limits, or error behavior, and the mark_read contradiction reduces trust in completeness.

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

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

Schema covers all 5 parameters with descriptions. The description adds value by providing an example filter ('sec_8k'), explaining ISO timestamp usage, and clarifying that mark_read affects subsequent calls. This 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 it 'Pulls fired events from your subscription feed' and specifies return fields (source, citation_uri, payload) and filtering options. This distinguishes it from sibling tools like list_subscriptions or recent_changes.

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 polling ('Polls work fine') and notes the same feed is available as a direct endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds important behavioral details: fans out to multiple sources, GDELT→GNews fallback mechanism, USPTO soft-fail until reactivated, and return format including citation URIs. This 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 front-loaded with example queries, making the purpose instantly clear. It covers sources, fallback, parameters, return structure, and sibling comparison in a dense but readable paragraph. Slightly longer than minimal, 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?

Given the tool's complexity (multiple data sources, fallback, limitations), the description is remarkably complete. It explains return format (grouped changes, count, URIs), handles edge cases like USPTO soft-fail, and provides clear parameter guidance. Even without an output schema, the description compensates 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%, but the description adds further context: examples for 'since' (ISO date and relative shorthand like '30d'), accepted formats for 'value' (ticker or zero-padded CIK), and enumeration for 'type' (only company). Significantly 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 defines the tool as providing a 'change feed for a company' that fans out to SEC EDGAR, GDELT→GNews, and USPTO. It includes example queries and directly distinguishes from sibling tool 'entity_profile' (static 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 usage examples like 'What's new with X', 'latest on Y', and specifies when not to use it: 'Use entity_profile instead when you want the static profile regardless of window'. Gives clear context for when this tool is appropriate.

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds value by explaining scoping by identifier and persistence duration (24 hours for anonymous, persistent for authenticated). No contradictions detected.

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

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

Four sentences, each adding unique value: purpose, usage scenario, scoping/persistence, and pairing with sibling tools. 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?

The tool has only two simple parameters, no output schema, and low complexity. The description covers all essential aspects: what it does, when to use, how it's stored, and relationship to other tools. Nothing missing.

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

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

The input schema has 100% parameter description coverage with clear examples. The description enhances this by illustrating usage patterns ('a resolved ticker, a target address') and providing context for both key and value beyond the schema's generic 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 starts with a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly stating what the tool does. It distinguishes itself from sibling tools by naming recall and forget as complementary actions.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward'), provides exclusion guidance (anonymous vs authenticated users), and names alternative tools (recall, forget), giving the agent clear decision context.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it cascades through multiple internal endpoints, returns citation URIs, and handles auto-disambiguation for companies. 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 moderately long but well-organized with examples upfront. Every sentence adds value, though it could be tightened slightly. The structure guides the user quickly to the tool's purpose and usage.

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?

Without an output schema, the description fully explains return values for each type (ticker, CIK, company name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It covers internal behavior and the fact that it replaces multiple manual lookups, leaving no major 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 already describes both parameters with 100% coverage. The description enriches by giving concrete input examples (e.g., 'AAPL', '0000320193', 'ozempic') and noting auto-disambiguation for company type, adding clarity beyond the schema.

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

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

The description opens with concrete natural language examples ("What's the ticker for…") and explicitly defines the tool's function: resolve a name to a canonical identifier. It clearly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID.'

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

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

The description provides a clear directive ('Use FIRST') and lists supported entity types with their outputs. It does not explicitly state when not to use it, but the context strongly implies it is for identifier lookups when a name is available.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. This provides useful behavioral detail beyond the annotations without contradiction.

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

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

Four concise sentences front-load the purpose ('Compare AI visibility...') followed by process, use case, and return info. 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 no output schema, the description explains return format (ranked list with score, confidence, signal density). It covers input constraints (2-8 entities, first as subject). Missing details on error handling (e.g., if entities out of range or model unavailable), but for a read-only tool with annotations, it's largely sufficient.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning: 'entities' first entry is the subject, 2-8 items required, 'models' defaults to workers-ai, requires _apiKey for anthropic, and 'context' disambiguates common names. This enriches 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 compares AI visibility across multiple entities, uses ai_visibility_check under the hood, ranks results, and surfaces the most/least recognized. It distinguishes itself from siblings like ai_visibility_check (single entity) and compare_entities (likely generic) by being specific to AI presence.

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

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

The description provides a clear use case ('competitive AI-marketing audits') and an example question. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or directly name alternatives, though the context signals sibling tool ai_visibility_check as the single-entity option.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds beyond that: mentions partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. No contradictions with annotations.

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

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

The description is well-structured with a lead sentence summarizing the composite check, followed by usage guidance, return structure, ecosystem scope, and failure behavior. While it is somewhat long, every sentence adds necessary information. A slightly more concise phrasing could improve it further.

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 (multi-source composite, no output schema), the description adequately covers the return contents (summary block, per-advisory detail, links, alternative versions), ecosystem limitations, partial failure behavior, and timing warnings. No gaps identified.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying that scoped packages (e.g., '@types/node') are accepted and that version defaults to latest when omitted. This provides additional semantic clarity beyond the schema.

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

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

The description clearly defines the tool as a composite check for evaluating npm packages, combining deps.dev and bundlephobia data. It specifies the verb (scan), resource (dependency), and context (npm ecosystem). It distinguishes from sibling tools like deps.dev:version and other scanning tools by explicitly stating scope and 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?

The description explicitly states when to use: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'. This gives clear guidance on alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the return-shape note (IDs, titles, dates, blurb) which complements and does not contradict the annotations. It doesn't describe pagination mechanics or rate limits, but annotations carry the bulk safely.

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, zero waste. States the database, the filter combination, and the return shape concisely. Every clause carries 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?

With an output schema present and 100% parameter coverage plus rich annotations (read-only, idempotent, non-destructive), the description covers what a search tool needs: what it searches, what filters, and what it returns. A short mention of result ordering or the blurb source would push it to 5, but this is complete for the structured context 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 parameters are fully documented in the schema itself (limit range, query semantics, offset type, date formats). The description adds the return shape but not parameter-specific detail beyond schema. Baseline 3 applies appropriately.

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

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

The description uses a specific verb+resource ('Search the AI Incident Database') and clearly states what it returns ('incident IDs, titles, dates, and a short blurb'). It distinguishes from siblings like get_incident (single record) and list_recent (recent items), establishing this as the free-text/criteria search 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 names the two combining filters (free-text + date range) which provides clear context for when to use this vs list_recent or search_within. It doesn't explicitly name alternatives or give when-not guidance, but the sibling context makes the distinct search role clear.

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

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

While annotations already provide readOnlyHint, idempotentHint, etc., the description goes beyond by disclosing the embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping windows), and size limit (200K chars with truncation flag). This adds critical 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 consists of three dense sentences: the first states the core function, the second gives a use case, and the third adds technical details. Everything is front-loaded and every sentence earns its place.

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

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

Despite lacking an output schema, the description explains return values (top-N passages with character offsets and similarity scores). For a tool with 3 simple parameters, this fully covers what an agent needs to know, including pairing guidance.

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

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

With 100% schema description coverage, the description still adds value by explaining how to use the 'text' parameter ('text you already pulled') and the 'query' parameter ('natural-language query') with examples. It also notes the default for 'limit' (5).

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

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

The description clearly states the tool performs semantic search inside a fetched record, with examples like SEC 10-K or article. It distinguishes itself from siblings by explicitly mentioning pairing with ask_pipeworx_grounded, making its unique purpose unmistakable.

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

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

The description provides strong guidance on when to use: 'Use when the record is too big to cram into the prompt' and explains the benefit of saving context. It also advises pairing with ask_pipeworx_grounded, though it doesn't explicitly state when not to use alternatives.

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

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

The description fully discloses behavioral traits: creation action (consistent with readOnlyHint=false), authentication requirement, type-specific filtering, delivery channels with operational details (webhook auto-disable, HMAC signing, SMS cap). This goes beyond annotations to provide comprehensive behavioral transparency.

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

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

The description is well-structured and front-loaded with the main purpose. It is comprehensive but slightly verbose; every sentence adds value, making it appropriate for the tool's complexity.

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

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

Despite no output schema, the description covers all necessary aspects: subscription lifecycle, type-specific parameters, delivery channels, side effects (phone verification, secret return), and failure behavior. It provides complete context for a complex tool.

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

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

The description enriches the input schema by explaining each type's parameters with concrete examples (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailing delivery sub-parameters (email, SMS, webhook with security practices). Schema coverage is 100%, and the description adds significant value.

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: creating a proactive monitoring subscription to a live-data event stream and returning the new subscription ID. It differentiates from sibling tools like 'unsubscribe' and 'list_subscriptions' by specifying its create action.

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 detailed usage context: requires a Pipeworx OAuth account, lists supported types with examples, and outlines delivery channel options with constraints (e.g., phone verification, SMS cap). While it doesn't explicitly contrast with all sibling tools, the context sufficiently guides appropriate 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=true, idempotentHint=true, etc. The description adds value by explaining that the tool returns tool + argument shapes from a live catalog and is an onboarding step. No contradiction with annotations.

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

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

The description is front-loaded with example questions and structured with categories. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall well-organized.

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

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

Despite lacking an output schema, the description thoroughly explains the return value (category-bucketed example questions with tool+argument shape). It covers purpose, usage, parameters, and context. No gaps for an onboarding 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% for the single optional parameter. The description adds meaning by explaining that omitting topic gives a cross-category spread, which is not in the schema description. This helps the agent understand default behavior.

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 returns category-bucketed example questions and serves as the onboarding entry point. It distinguishes itself from sibling tools by specifying it should be used first when the user doesn't know what Pipeworx can do. The verb 'returns' and resource 'example questions' are specific.

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 to call with no arguments for full spread or pass a topic to focus. Provides context: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' Does not explicitly state when not to use or list alternatives, but the 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?

Adds value beyond annotations by clarifying that cancellation deactivates rather than deletes, and that historical events remain accessible. 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?

Two concise sentences that front-load the purpose and then provide critical behavioral details. 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?

Covers the primary behavior and constraints, but missing description of the response format, error handling, or idempotency effects. Adequate for a simple tool, but not fully 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 has 100% coverage for the single parameter. The description does not add additional semantic detail beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

Cleary states the verb 'cancel' and resource 'subscription'. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

Explicitly notes ownership enforcement, guiding the agent to only cancel subscriptions belonging to the current user. Implicitly contrasts with 'subscribe' and 'list_subscriptions' but does not fully enumerate 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 nondestructive. The description adds significant context: the two processing paths (structured SEC vs. grounded pipeline), the return verdict types, and the inclusion of citations. 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 longer but well-structured: starts with trigger phrases, then usage, processing details, return format. Some redundancy exists but every sentence contributes to understanding.

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

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

Despite no output schema, the description fully explains return values (verdict types, actual value with citation, reasoning). It covers both processing paths and parameter behavior, making it complete for a 2-parameter tool.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining tolerance_pct overrides implied tolerance and gives a usage example for hallucination detection, which goes beyond 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 begins with natural-language triggers, states the tool verifies factual claims against authoritative sources, and explicitly distinguishes it from siblings by noting it replaces 4-6 sequential calls. It clearly communicates the verb+resource (validate claim) and 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It differentiates between company-financial claims and other claims, but does not provide explicit when-not-to-use scenarios.

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