Dart Kr

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the probing nature, free default model, BYO key for Anthropic, and return format. It does not contradict annotations and provides useful behavioral context beyond them.

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

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

The description is moderately concise and well-structured: first sentence states main purpose, then parameter details, then use cases. It could be slightly more terse but is well-organized and front-loaded.

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

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

Despite no output schema, the description outlines the return structure (per-model score, confidence, signals, raw_response + combined view). It covers all critical details for a probing tool: entity, optional models, API key handling, and context. No gaps in essential information.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description adds meaningful context: default model explanation for 'models' parameter, BYO key clarification for '_apiKey', and usage context for 'context'. This goes beyond what the schema provides.

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

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

The description uses a specific verb ('Probe') and resource ('LLMs for knowledge about a business/brand/product/topic') and clearly states it scores visibility 0-100. It distinguishes from siblings by focusing on AI visibility scoring, which is unique among the sibling tools.

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

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

The description explicitly states when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains default model and optional Anthropic probe. However, it does not explicitly mention when not to use it or compare to alternatives like scan_competitor_ai_presence or entity_profile.

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

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

Annotations already cover readOnly/openWorld/idempotent/non-destructive. The description adds valuable context: it routes to sub-tools, auto-fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and makes a single fast call. This goes beyond the structured metadata.

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 front-loaded with the key directive ('PREFER OVER WEB SEARCH') and organized into scannable sections (scope, routing, alternatives, examples). Each sentence adds meaningful information, so it earns its length despite being verbose.

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

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

This tool spans a huge domain, and the description covers routing behavior, output format (structured answer with citations), tier compatibility, and explicit alternatives. Without an output schema, it provides enough information for an agent to decide when and how to invoke it, and what to expect in return.

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

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

The schema has 100% coverage with clear descriptions for 'question' and aliases. The description enriches this with example queries and phrase patterns ('what is', 'look up', 'find', 'get the latest'), which help the agent formulate the parameter value even though the schema already explains the field.

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 ('routes') and resource ('questions to 5,439 tools across 1412 verified sources'), with clear examples of what it does. It explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its scope 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 strong, explicit guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', while also specifying when to escalate to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It covers when-not-to-use as well.

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 behavioral traits beyond the annotations: it may have candidate routing improvements enabled live, currently matches ask_pipeworx exactly because no candidate is active, and results are compared against the stable router. This provides critical context about the experimental nature and potential behavior changes, which the annotations alone do not convey.

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

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

Three sentences deliver a wealth of specific information: the beta identity, the current no-candidate state, usage instructions, and a clarification that it is a full working router. Each sentence serves a distinct purpose, and the description is front-loaded with the most important fact (beta version of ask_pipeworx).

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

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

The description covers the tool's identity, usage, current behavior, and relationship to the stable router, which is sufficient for a universal router with no output schema. It relies on the sibling ask_pipeworx for the response shape, but that is acceptable given the sibling context. The only minor gap is that 'same response shape' is vague without prior knowledge of ask_pipeworx.

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

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

The input schema already provides 100% coverage for all 6 parameters (all aliases for 'question'), so the baseline is 3. The description does not add any parameter-specific semantics beyond noting 'same arguments' as ask_pipeworx, which does not add new meaning for an agent already seeing the schema.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router identical to the stable version except for candidate routing improvements. It distinguishes itself from siblings by explicitly naming ask_pipeworx and emphasizing the beta/experimental nature.

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

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

Explicitly tells the agent when to use it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it is a full working router, not a fallback, which prevents misuse. The contrast with the stable router is implicit but 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 note readOnly and idempotent, but the description adds significant behavioral detail: the exact return payload, refusal reasons (not_in_source, no_tool_match, etc.), and the 'ONLY what the tool result contains' constraint. It also discloses the extra LLM call cost, going beyond annotation hints.

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

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

The description is dense but every sentence provides distinct value: purpose, routing behavior, return shape, refusal semantics, usage context, and cost tradeoff. It is front-loaded with the key concept and avoids redundancy despite its length.

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

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

Despite having no output schema, the description fully specifies the return structure and refusal envelope. It covers usage context, limitations, and relationship to ask_pipeworx, making it complete for selecting and invoking the tool correctly.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for the natural-language question. The description adds no extra parameter meaning beyond what the schema already states, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its core behavior: routing like ask_pipeworx, fetching data, and extracting answers only from the tool result. It distinguishes from sibling ask_pipeworx by emphasizing evidence-based answers and refusal handling.

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 when-to-use guidance is given: use when an answer will be quoted, cited, or acted on and must not invent facts (e.g., financial, legal, medical). It also provides the alternative and tradeoff: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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 extensive behavioral details beyond annotations: market resolution, classification, fan-out, response shapes, safety short-circuits, resolver contract, parent event extraction, news fallback, and blocking behaviors. 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?

Front-loaded with core purpose but very long and dense single paragraph. Lacks structured formatting (e.g., bullet points) for readability. Every sentence adds value but could be more concise and better 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?

No output schema, so description fully explains return values: result fields, resolver contract, parent event, news fields, safety behaviors, and edge cases. Covers all aspects needed for an agent to use the tool correctly.

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

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

Schema covers 100% of parameters with descriptions. Description adds value by explaining market input formats (slug, URL, question text) and examples for depth/include_raw. Some extra context provided 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 the tool researches a Polymarket bet by pulling Pipeworx data, with specific usage examples like 'should I bet on X'. Differentiates from sibling tools by focusing on Polymarket bets and Pipeworx 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?

Explicitly says what to use it for ('use for should I bet on X'), includes safety warnings to inspect fields before trusting analysis, and mentions resolution-rule risk before sizing bets. Provides clear context despite not listing 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) declare safe, read-only, idempotent behavior. Description adds significant context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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?

Concise 3-4 sentence description front-loaded with user-query examples. Every sentence adds value: usage patterns, data specifics, and efficiency claim. No redundancy.

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

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

Given 2 required params, no output schema, and rich annotations, description covers what each type returns, result sorting, and replaces many lookups. Lacks details on error handling or response format but sufficient for 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 coverage is 100% with descriptions for both 'type' and 'values'. Description enriches by explaining what data each type pulls (e.g., 'latest 10-K revenue + net income' for companies, 'FAERS adverse-event counts' for drugs) and provides examples for 'values'.

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 leads with clear example queries ('Compare X and Y', 'X vs Y', 'which is bigger') and explicitly states the action: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call'. It distinguishes from sibling tools by advising 'ALWAYS PREFER over sequential single-pack 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 when-to-use examples covering typical comparison scenarios (e.g., 'rank these companies', 'head to head'). States preference over sequential lookups. Missing explicit when-not-to-use but context is strong.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, covering safety and behavior. The description adds value by listing the returned fields and the purpose, which complements 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?

The description is concise with two sentences. The first sentence lists the fields, and the second provides usage guidance. Every sentence is necessary and well-structured, front-loading the most important information.

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

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

Despite no output schema, the description lists all expected return fields (corp_name, stock_code, CEO, market tier, industry code, address, founding date, fiscal-year-end month, homepage), making the output clear. It also provides usage context, making it complete for a simple lookup tool.

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

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

The input schema already describes the parameter (8-digit DART corp identifier) with 100% coverage. The description adds context by explaining that the corp_code typically comes from dart_search_filings, which is useful for understanding parameter origin, but does not add new syntax or constraints beyond the schema.

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

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

The description clearly states the tool returns a basic profile for a Korean DART-registered company and lists the specific fields (corp_name, stock_code, CEO, market tier, etc.). It also distinguishes from siblings by noting it is used after dart_search_filings to enrich corp_code or as a first lookup.

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 when to use the tool: after dart_search_filings to enrich a corp_code into a readable entity, or as the first lookup when given a corp_code with no context. This provides clear guidance and suggests alternatives (other tools for financials, etc.).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by clarifying the output includes current and prior period amounts and that data goes back to 2015, offering behavioral context 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?

Three sentences with no wasted words; front-loaded with the core purpose, then usage guidance, then pairing recommendation. Excellent conciseness and structure.

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

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

Given high schema coverage and no output schema, the description adequately covers what the tool returns (income statement, balance sheet, cash flow items) and example line items. It could mention output format, but for fundamental analysis it is sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds contextual value (e.g., pairing suggestion, example line items) but does not significantly deepen parameter-level meaning beyond the schema.

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

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

The description clearly states that the tool retrieves key financial line items from Korean company periodic reports, specifying the types of statements and periods. It does not explicitly distinguish from sibling tools like dart_company_info or dart_insider_holdings, but those have obviously different purposes, so the purpose is clear.

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

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

The description advises using the tool for fundamental analysis on KOSPI/KOSDAQ filers and suggests pairing with ecos_get_series for macro context. This provides practical guidance, though it lacks explicit when-not-to-use or alternative tool mentions.

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, covering safety. Description adds value by detailing the return fields and the analogy to US Form 4, but does not mention rate limits or auth requirements.

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

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

The description is concise: two sentences, front-loaded with the key purpose and use cases. No unnecessary words or redundancy.

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

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

Given one parameter and comprehensive annotations, the description adequately explains the return fields and use cases. It could mention data freshness or historical scope but is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 100% for the single parameter 'corp_code', which has a clear description. The tool description does not add additional parameter-level information beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool returns insider equity-holding disclosures for Korean executives and major shareholders, listing specific fields and drawing analogy to US Form 4. It distinguishes from siblings like dart_major_shareholders by specifying 'insider transactions' and executive compensation analysis.

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

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

The description explicitly recommends use for insider-trading signal, executive compensation analysis, and family ownership tracking. It does not explicitly exclude alternatives but provides clear use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds context about regulatory threshold (5%) and equivalence to US filings, enhancing 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?

Two sentences with no redundancy: first defines functionality and output, second gives usage context. 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?

Given single parameter and safe read-only nature, description covers return fields, regulatory background, and use cases sufficiently despite lack of output schema.

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

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

Schema description for corp_code is already clear (8-digit DART identifier). Description does not add further details; baseline 3 due to 100% schema coverage.

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

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

Clearly states it retrieves Korean 5%-rule disclosures for a company, specifies returned fields (shareholder name, holding type, shares, stake, change reason, report date), and compares to US 13D/13G. Distinct from sibling tools like dart_insider_holdings.

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

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

Provides explicit use cases: 'who owns big stakes in $KR_COMPANY', activism tracking, follow-the-money on KOSPI filings. Lack of explicit when-not-to-use or alternative mentions is minor given clear context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds useful behavioral details like default date ranges (30 days ago to today) and that omitting corp_code searches all companies, providing transparency beyond annotations.

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

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

The description is a single, focused paragraph that front-loads the purpose and immediately lists key return fields. It uses no filler sentences and has a natural flow from purpose to filters to examples.

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

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

The description covers the tool's core functionality, return fields, and filtering options. Although there is no output schema, the description mentions the key return fields (rcept_no, rcept_dt, etc.). It misses some nuances like pagination but is complete for most use cases.

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 adds value by giving concrete examples for corp_code (e.g., '00126380' for Samsung) and expanding on pblntf_ty categories (e.g., 'B (major events)'). This enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool provides an 'AUTHORITATIVE list of recent Korean corporate disclosures' from DART, with specific fields returned. It includes concrete use cases like 'what did Samsung file last week', distinguishing its purpose effectively.

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 usage examples (e.g., filtering by company, date range, filing type) and specifies the tool is for recent filings. It doesn't explicitly mention when not to use or alternatives, but the context is clear enough for an AI agent.

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

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

Even with readOnlyHint and idempotentHint annotations, the description goes far beyond: it discloses the findings packet fields (verbatim evidence + confidence + source + fetched_at + citation), explicit gaps[] never-invented policy, contradictions[] scan, hop field, excerpting behavior, and time expectations (15-60s, up to ~90s). 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 every sentence adds necessary context for a complex tool: prerequisites, alternatives, behavior, output, and performance. It front-loads the critical account requirement and alternative-tool hint. It's dense but well-structured with clear separators, though it could benefit from bullet points for scannability.

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

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

Despite having no output schema, the description fully covers return values, side effects, errors, latency, account tiers, and when to use alternatives. It is complete for a complex multi-tool orchestrator with 2 params. The only minor missing detail is the exact structure of the findings packet, but the description names all key fields.

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

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

Schema coverage is 100% with good parameter descriptions, but the description adds behavioral nuance beyond schema: it explains how depth values affect gap recovery and lead-chasing in practice. It also clarifies that 'standard' is default, which the schema implies but doesn't state. This adds genuine 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 is exceptionally clear: 'Grounded multi-source research across Pipeworx's 1412 STRUCTURED data sources...' uses a specific verb+resource and explicitly contrasts with open-web search. It also differentiates from siblings like ask_pipeworx, stating this executes parallel tool routing vs. a single LLM call.

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

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

It provides explicit usage boundaries: 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx.' It also requires sign-in and points to ask_pipeworx for unsigned users, naming the alternative directly. This is model guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and description does not contradict. Description adds behavioral context: results are ready to call directly with full schemas, no second lookup needed.

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

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

Description is a single paragraph, front-loaded with the core purpose. It lists many categories, which is useful but slightly wordy. Could be tightened without losing meaning.

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

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

No output schema, but description explains what is returned (top-N tools with names, descriptions, schemas). Sufficient for a discovery tool with read-only, idempotent behavior.

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

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

Schema coverage is 100% (all 6 parameters documented). Description adds value by explaining aliases for 'query,' providing examples, and stating defaults for 'limit.'

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

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

Description starts with 'Find tools by describing the data or task,' which is a specific verb+resource. It lists many categories (SEC filings, FDA drugs, etc.) and distinguishes from sibling tools that are specific data tools.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implying not to use when you already know the tool.

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

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

Annotations already cover safety traits. The description adds behavioral details like parallel fan-out across sources, the USPTO API sunset date, soft-fail behavior, and return structure, which adds value beyond annotations.

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

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

The description is a single paragraph that conveys much information efficiently and front-loads example queries. It is concise but could benefit from structured layout (e.g., bullet points) for even easier parsing.

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

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

Given the tool's complexity (multiple sources, no output schema), the description comprehensively lists all return fields (CIK, filings, fundamentals, patents, news, LEI) and notes limitations (patents sunset). It is complete for an agent to understand expected output.

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

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

Schema coverage is 100% and describes parameters. The description adds context: value can be ticker or CIK (with examples), and clarifies that names are not supported, enhancing understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific example queries and distinguishes from sibling tools like resolve_entity and single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack...' and advises using resolve_entity when only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and operating on memory, which is consistent and helpful 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?

Two sentences, no unnecessary words, and front-loads the core action. Every sentence adds value.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose and usage. However, it lacks details on what happens if the key doesn't exist or confirmation of success, which would improve 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 coverage is 100%, so the parameter 'key' is already described. The description only mentions 'by key' and the example provides a sample, adding minimal extra meaning beyond the schema.

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

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

The description clearly states 'Delete a previously stored memory by key,' which is a specific verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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

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

The description provides explicit when-to-use scenarios: stale context, task done, clearing sensitive data. It also suggests pairing with remember and recall, giving context for usage but not explicitly 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?

Description adds value beyond annotations by detailing the process (fetches page, extracts title/description/key links) and output format. Annotations already declare readOnlyHint, idempotentHint, and non-destructive, and description aligns 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 concise with three sentences plus a bullet list, front-loading the main action and output. Every sentence earns its place with no redundancy.

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

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

Given the simple operation (2 params, no output schema), the description fully covers what the tool does, how it works, and the output format. No gaps remain for effective usage.

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

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

Schema coverage is 100%, so baseline is 3. Description briefly mentions max_links defaults (25, max 50) which is already in schema, adding no significant new meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose: generate a production-ready llms.txt file for any URL. It specifies the output format and distinguishes itself from siblings like ai_visibility_check and scan_competitor_ai_presence by focusing on llms.txt generation.

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

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

The description lists concrete use cases (getting client site indexed, drafting own llms.txt, auditing competitor), providing clear context for when to use. It lacks explicit when-not or alternative tool recommendations, but the use cases sufficiently guide selection.

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

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

Annotations already declare readOnlyHint, non-destructive, idempotent. Description adds specific return fields and the optional parameter behavior (include_inactive). No contradictions.

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

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

Two sentences, succinct and front-loaded with the core action. No extraneous words.

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

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

For a simple list tool with 1 optional param and good annotations, the description fully covers purpose, return fields, and usage context. No output schema needed.

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

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

Schema coverage is 100%, so baseline 3 is appropriate. Description does not add detail beyond the schema's description of include_inactive, but it does clarify default behavior (active only).

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 it lists the caller's active subscriptions and lists the return fields. The verb 'List' and resource 'subscriptions' are explicit, and the description distinguishes it from sibling tools like subscribe/unsubscribe.

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

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

Provides context on when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. It implicitly advises against adding without first reviewing, but does not explicitly mention alternatives like subscribe or unsubscribe.

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 behavioral constraints not present in annotations: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also explains downstream impact ('digests daily and signal directly affects roadmap'), adding valuable context beyond the structured hints. 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 purpose, then flows logically into use cases, exclusions, message tips, and constraints. Every sentence serves a distinct function—there is no fluff. Despite its length, it remains tightly organized and scannable, with no redundant phrasing.

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 feedback tool with no output schema, the description fully covers relevant context: what to report, how to frame it, exclusion criteria, rate limits, and operational impact. It leaves no ambiguity about the tool's role, scope, or expected usage, making it remarkably 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 covers 100% of parameters with clear descriptions, so baseline is 3. The description adds extra semantic guidance for the 'message' parameter with 'don't paste the end-user's prompt' and 'Describe the issue in terms of Pipeworx tools/packs,' which enriches the parameter's intended content beyond the schema's generic 'be specific' advice.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the tool's action and resource. It also distinguishes this tool from siblings by explicitly scoping it to 'tools served by this Pipeworx connection,' a unique clarifier not present in sibling names.

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

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

Explicit 'Use when' conditions are given for each feedback type (bug, feature/data_gap, praise). It also provides a clear exclusion: 'ONLY for tools served by this Pipeworx connection' and offers a fallback rule ('Not sure? Pipeworx tool names are the ones this connection lists'). This is precisely the guidance needed to choose the right recipient.

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 (readOnly, openWorld, idempotent) already declare safety; description adds caching details (5min–1h) and confirms no PII. No contradictions, and adds useful behavioral context 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?

Approximately 4 sentences, front-loaded with main output, then use cases, then caching note. Every sentence adds value; no redundancy or filler.

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

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

Explains return fields (top tools, packs, volume) and caching. With no output schema, it provides sufficient context for typical use. Could mention potential limits (e.g., top N count), but not critical for clarity.

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?

Single parameter 'window' with enum values fully described in schema. Description adds semantic nuance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', which enriches the schema's enum list.

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

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

Clearly states the tool returns trending call data (top tools, top packs, volume) over configurable windows. The verb 'returns' and specific resource model it well from siblings like ask_pipeworx (direct Q&A) or discover_tools (broader discovery).

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?

Lists three concrete use cases (hot data sources, canonical tool confirmation, use case alignment). Lacks explicit when-not-to-use or direct sibling comparisons, but the use cases provide strong contextual guidance.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: internal logic (Jaccard similarity, partition filter, placeholder detection), fill check mechanics, and edge cases. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though some details could be more terse. Well front-loaded with 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?

Given the tool's complexity (multiple modes, intricate checks) and lack of output schema, the description thoroughly covers expected outputs (opportunities array, fill check details) and operational constraints, providing a complete picture for the 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?

Both parameters are documented in the schema (100% coverage). The description adds meaning beyond the schema by explaining what constitutes a valid event slug vs topic seed question, providing concrete examples, and clarifying the no-args 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 the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args (trending scan), event (single event), and topic (cross-event), each with a specific verb and resource, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly guides when to use each mode: 'Call with NO args for a trending_scan... pass event for... or topic for...'. It explains cross-event mode catches patterns single-event misses, and provides a fill check warning not to trade if realizable edge <= 0, offering clear decision criteria.

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

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

Annotations declare readOnlyHint and idempotentHint; description adds extensive behavioral detail: three model families with formulas, edge calculation (net of slippage), caching at KV level for 1h, diagnostics for why segments are empty, and 24h-move warning. Fully transparent with no contradictions.

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

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

Description is thorough but long (~600 words). Well-structured with sections for segments and knobs, front-loading purpose. However, some detail could be condensed for easier parsing while retaining value.

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

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

Despite no output schema, description explains response structure (by_segment, fed_candidates, _diagnostics), covers inputs, behavioral traits, filters, and caching. 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?

All 9 parameters have schema descriptions; description enriches them with practical context (e.g., min_liquidity: 'Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven'). Adds meaning beyond schema.

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

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

Description explicitly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifying three segments. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery and edge detection.

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?

Clearly positioned as 'what should I bet on today' for discovering opportunities without paging. Provides guidance on when to use and describes knobs like min_liquidity and max_spread_pp, but does not explicitly state when not to use or compare to alternatives, though 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond annotations: data comes from daily snapshots with 60-day TTL, decay computed from daily closes (not intraday), and snapshot gaps occur when no cache miss. 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 long but well-structured with clear subsections. It front-loads the core purpose and includes necessary details about response format and limits. Some redundancy (e.g., default values repeated) could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description fully explains the three response arrays (tracked, expired, snapshot_dates) with field semantics. It also covers data freshness and limitations (TTL, snapshot start). For a read-only telemetry tool with 2 well-documented params, this is highly complete.

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

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

Schema description coverage is 100% so baseline is 3. The description reiterates and slightly extends parameter meaning (defaults, clamp, window family), but adds limited new semantic value beyond the schema's existing descriptions.

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

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

The description uses specific verbs and nouns: 'Edge persistence and decay telemetry' and answers a concrete question about edge longevity and shrinkage. It clearly distinguishes from sibling tools like 'polymarket_edges' by focusing on historical time-series rather than current snapshots.

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

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

The description provides clear context for when to use this tool—to differentiate between fresh-wide edges and old-wide edges—and implies not to use it for current snapshot data. However, it lacks explicit when-not or alternative tool mentions, leaving room for ambiguity.

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 non-destructive. The description adds rich behavioral detail: how it walks the order book, returns like slip, shares_filled, max_fillable_usd, verdict, and per-leg details for baskets. It also explains the risk of partial fills converting directional risk, which is critical context beyond what annotations provide.

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

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

The description is well-structured: a concise opening sentence, organized breakdown of single-market and basket modes with return values, and a concluding advisory on usage. Despite its length, every sentence adds value, and the structure aids quick comprehension.

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 must cover return values, which it does exhaustively for both modes. It also explains edge cases (thin_legs, forced_directional_risk) and provides usage guidance. Four parameters are fully described in both schema and description, making the tool's operation complete 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 description coverage is 100%, baseline 3. The description significantly adds meaning: it explains the dual mode (market vs event), the interpretation of side defaults in basket mode, and how size_usd is interpreted as settlement notional in basket mode. This goes well beyond the schema's field descriptions, making parameter usage clear.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly links to sibling tools (polymarket_arbitrage, polymarket_edges) by stating when this tool should be used before them, providing strong differentiation.

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 usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns about the consequences of not using it (partial fills converting arb into directional risk) and clarifies required parameters (one of `market` or `event`), leaving no ambiguity about when to invoke 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: compatibility_warning conditions, temporal_alignment significance, and skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is well-structured into sections (overview, modes, response, safety fields) but is verbose at ~200 words. Some redundancy could be trimmed without losing information.

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

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

For a complex tool without output schema, the description fully explains response fields (leg-by-leg prices, spreads, compatibility_warning, temporal_alignment, skipped counters) and their meanings, ensuring the agent knows what to expect.

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

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

All 3 parameters are described in schema (100% coverage). The description adds extra meaning by listing the 10 topic shortcuts, providing examples for explicit tickers, and explaining override behavior. This exceeds the baseline 3 for high-coverage schemas.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', with specific verb+resource. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison and compatibility checking.

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

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

The description provides clear usage guidelines: two modes (topic shortcuts or explicit tickers), when to use (when same question appears on both venues), and when not (compatibility warnings and temporal misalignment make spreads meaningless). It also warns that most pre-mapped topics return warnings.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, which the description reinforces by describing a non-destructive retrieval operation. The description adds context about scoping and the dual behavior (single key vs. list all). No contradictions.

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

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

The description is three sentences with no waste. Each sentence serves a purpose: defining the action, giving use cases, and explaining scoping and related tools. Well structured and front-loaded with the key behavior.

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 one optional parameter and no output schema, the description adequately explains the two return modes and scoping. It could mention the return format (e.g., value or list), but overall it is complete for this simple 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 single optional parameter 'key' is documented in the schema, and the description adds meaning by explaining the behavior when omitted: 'omit the key argument to list all keys.' Schema coverage is 100%, and the description provides useful context beyond the schema.

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

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

The description clearly states the verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinguishes from siblings like remember and forget by describing when to use each, and provides concrete examples of stored context.

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

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

The description explains when to use the tool ('to look up context the agent stored earlier') and mentions pairing with remember and forget. It does not explicitly state exclusions, but the usage 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, destructiveHint. Description adds return field details, mark_read side effect, and polling suitability, enhancing transparency without contradiction.

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

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

Three sentences, each earning its place: purpose, return structure, filtering and mark_read behavior, alternative endpoint. Front-loaded and concise with no extraneous text.

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

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

No output schema, so description compensates by describing return fields (source, citation_uri, raw payload). Parameters are covered with examples and behavioral context. Includes polling guidance and alternative access method, making it complete for a read-only, idempotent tool.

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

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

Schema coverage is 100%, and description adds value with examples (type 'sec_8k', ISO timestamp) and behavioral explanation for mark_read. However, 'limit' and 'unread_only' parameters are not elaborated 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 clearly states the tool pulls fired events from the subscription feed, listing returned fields (source, citation_uri, raw payload). It provides a clear verb and resource, but does not explicitly differentiate 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?

Gives specific usage guidance: filtering by type and since, using mark_read for read tracking, and noting polling works fine. Provides context but lacks explicit when-not-to-use or alternative tool recommendations.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details the fan-out to multiple sources, the GDELT→GNews fallback, USPTO soft-fail, and the return structure. This adds significant behavioral context without contradiction.

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

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

The description is a single efficient paragraph that front-loads the purpose with example queries, then covers sources, parameters, return format, and the sibling tool note. Every sentence contributes distinct information, 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?

Despite no output schema, the description covers the return structure (changes, total_changes, citation URIs), source behavior, parameter semantics, and provides a usage guideline. The tool's complexity is fully addressed.

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

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

Schema coverage is 100%, but the description adds value by explaining the `since` parameter's formats (ISO date, relative shorthand) with examples, clarifying `type` is limited to 'company', and specifying `value` can be ticker or CIK. 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 the tool returns a change feed for a company in a time window, with specific verb+resource from example queries. It distinguishes from the sibling entity_profile, making the purpose unambiguous.

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

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

Explicitly says when to use (change feed) and when not to (static profile), naming the alternative tool (entity_profile). Provides example queries that help the agent identify usage scenarios.

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

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

Annotations declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which align with the description's claim of a non-destructive write operation. The description adds valuable behavioral context: memory is key-value scoped by identifier, authenticated users get persistent memory, anonymous sessions retain 24 hours.

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 concise, well-structured paragraph. It front-loads the core purpose, then gives usage guidelines, and ends with behavioral details. No unnecessary words or repetition.

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

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

Given the tool's low complexity (2 parameters, no output schema, no nested objects), the description covers all essential aspects: purpose, usage, storage behavior, scoping, persistence, and companion tools. 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?

Schema coverage is 100% and the description already explains the key-value pair concept. The description adds examples of key naming conventions (e.g., 'subject_property', 'target_ticker'), which provides extra semantic guidance.

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

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

The description explicitly states the tool saves data for later reuse and provides concrete examples (resolved ticker, target address, user preference, research subject). It also distinguishes from sibling tools 'recall' and 'forget' by naming them as companions.

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?

Clearly specifies when to use ('when you discover something worth carrying forward') and explicitly mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already convey safety (readOnly, idempotent). Description adds value by noting internal cascading through multiple endpoints, replacing manual lookups.

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

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

Well-structured with examples, usage hint, and bulleted type details. Slightly long but every sentence adds value. Front-loaded with example queries.

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?

Fully covers both entity types, input formats, return fields, and internal behavior. No major gaps despite lack of output schema.

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

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

Adds rich detail beyond the input schema: explains what each type returns (e.g., 'company' returns ticker + CIK + name), input formats accepted, and auto-disambiguation. Schema coverage is 100% but description significantly enhances 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 uses specific verbs ('resolve', 'look up') and clearly states the resource: 'canonical/official identifier'. It provides example queries and distinguishes itself from sibling tools by its unique role.

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 FIRST whenever you have a name but need an ID.' Does not list alternatives, but the tool's uniqueness is clear from the description and sibling list.

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

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

The description adds context beyond annotations: reveals internal call to ai_visibility_check, describes ranking and output format. Annotations already indicate readOnly, idempotent, etc., so description complements well 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?

Two sentences that pack purpose, mechanism, use case, and output summary without fluff. 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?

Given no output schema, description adequately explains return: ranked list with score, confidence, signal density. Covers prerequisites, use case, and what the tool produces.

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

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

Schema coverage is 100%, but the description adds useful context for models ('supported models'), _apiKey ('passed to api.anthropic.com'), and context ('disambiguates common names'). Briefly explains entities as subject vs competitors.

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 side-by-side, using ai_visibility_check internally, and ranks results. It distinguishes from sibling tools that operate on single entities (e.g., ai_visibility_check).

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 concrete use case ('does Claude know about us as well as our competitors?') and implies when to use this over ai_visibility_check (multiple entities). Could be more explicit about when not to use, but overall clear.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts. It also details return data including summary, per-advisory detail, links, and alternative versions. 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 information-dense and each sentence adds value. However, it is a single long paragraph; better structural formatting (e.g., bullet points) could improve readability without losing content.

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

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

Given the tool's complexity (composite with multiple sources, potential failures), the description covers key aspects: purpose, usage, behavioral traits, edge cases (partial failures), and return structure. No output schema, but the description adequately describes output components.

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

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

Schema description coverage is 100% with both parameters well-described. The description adds that package accepts scoped packages and version defaults to latest, but this is minimal additional context. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states it is a composite check for npm packages, combining deps.dev and bundlephobia data. It specifies the verb 'scan' with the resource 'dependency' and distinguishes itself from sibling tools that focus on other domains.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also specifies limitations: NPM ecosystem only and for other ecosystems use deps.dev directly, providing clear when-to-use and when-not-to.

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?

Disclosure extends beyond annotations, detailing embedding model (BGE-base-en), window size (500-char overlapping), token limit (200K char truncation with flag), and output structure (character offsets, similarity scores). 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?

Compact yet comprehensive. Front-loaded with core purpose, then usage guidance, then technical details. Every sentence adds value with no redundancy.

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

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

Despite no output schema, description explains return format (top-N passages with offsets and scores) and covers all key aspects: input, behavior, limits, and integration with sibling tool. Complete for a 3-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%. Description adds practical meaning: text param explained as document text with max chars, limit param with default and range, query with natural-language examples. Adds value beyond schema.

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

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

The description explicitly states 'Semantic search INSIDE a fetched record' with a specific verb and resource, and distinguishes from sibling tools like ask_pipeworx_grounded. It clearly defines the action, input, and output.

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: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. Clearly states when and how to use the tool.

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

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

Discloses beyond annotations: returning subscription id, persistence requirement, webhook auto-disable after 10 failures. Covers key behavioral traits but could mention general rate limits.

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

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

Front-loaded with core purpose, then details. A bit lengthy but every sentence provides value. Minor redundancy (e.g., phone verification mentioned twice) could be trimmed.

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

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

Given complexity (3 params, nested objects, no output schema), description covers return value, all parameters with examples, authentication requirements, and delivery channel behaviors. Complete for a subscription creation 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?

Adds significant meaning beyond schema: provides type-specific examples (e.g., sec_8k items), delivery channel details, and required phone verification context. Fully compensates for any schema gaps.

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 'Create' and the resource 'proactive monitoring subscription', with explicit return value. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

Explicitly states OAuth requirement and lists supported types with channel constraints (e.g., SMS cap, phone verification). Does not explicitly name alternatives but provides sufficient context for when to use this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining the return format (category-bucketed examples with tool+argument shape) and the effect of the topic parameter, without contradicting annotations.

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

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

The description is informative and front-loaded with purpose, but it is somewhat verbose. Every sentence contributes value, but it could be slightly more concise without losing meaning.

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

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

Despite lacking an output schema, the description thoroughly explains the return format, parameter behavior, and usage context. It is complete for a simple onboarding 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?

The schema coverage is 100%, and the description adds meaning by listing possible topic values and explaining that omitting the parameter gives a full cross-category spread. This adds 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 returns category-bucketed example questions for Pipeworx and serves as an onboarding entry point. It distinguishes itself from sibling tools like ask_pipeworx by focusing on suggestions rather than direct queries.

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 this tool first when unsure what Pipeworx can do and to learn how to call meta-tools. It provides clear context but does not explicitly state when not to use it or mention 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?

Adds significant behavioral context beyond annotations: 'Ownership is enforced', 'row is deactivated (not deleted)', and 'historical events stay available via recent_alerts'. Annotations indicate non-destructive and idempotent, which aligns with description.

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

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

Two sentences, no wasted words. Front-loaded with action, followed by constraints and side effects. Highly efficient and clear.

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

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

Completely covers purpose, constraints, side effects, and references sibling tool for historical view. Given single parameter and no output schema, no additional information 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?

Only one parameter 'id' with schema description already clear. Description adds 'by id' but does not provide additional meaning beyond schema. Schema coverage is 100%, so baseline 3 applies.

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

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

Clearly states 'Cancel a subscription by id' with specific verb (cancel) and resource (subscription). Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by adding ownership and deactivation details.

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

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

Explicitly states when to use (cancel own subscription by id) and important constraints (ownership enforced, only own subscriptions). Provides context on what happens (deactivation not deletion) and mentions sibling 'recent_alerts' for historical events.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context about the two processing pipelines, the verdict types, and that it replaces multiple sequential calls. 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 fairly concise given the complexity, with key information front-loaded (natural language examples). It efficiently packs details about the two paths, return values, and efficiency gains. Slightly verbose but well-structured.

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

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

Despite lacking an output schema, the description clearly states what is returned: verdict, grounded or structured value with citation, and reasoning. It covers the two distinct processing paths and explains why this tool is efficient (replaces 4-6 calls). Complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description adds nuance by explaining the tolerance_pct override and default behavior (implied by wording, capped at 5). This provides additional context beyond the schema.

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

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

The description clearly states it performs natural-language claim verification against authoritative sources, uses examples of user queries, and distinguishes between company-financial claims and other factual claims. It precisely defines the tool's purpose 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 also outlines two different processing paths. However, it does not explicitly state when not to use this tool or suggest alternatives, which would improve clarity.

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