Ashby

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the default model, costing implications (free vs. BYO key for Anthropic), and the return structure (per-model and combined view), which goes beyond annotations.

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

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

The description is four sentences, front-loaded with the main action, and every sentence adds value. No redundant or filler 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?

Despite no output schema, the description provides a clear return format (score, confidence, signals, raw_response per model plus combined view). Parameters and usage are fully covered. The tool's complexity is moderate and the description feels complete.

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

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

Schema coverage is 100%, and the description still adds meaning: it specifies supported model values, explains the purpose of `_apiKey` and `context`, and clarifies the optional nature of `models`. This enhances parameter understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs about an entity and scoring visibility. The verb 'probe' and resource 'LLMs' are specific, and it distinguishes itself from sibling tools which focus on specific data sources like Ashby or Polymarket.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the API key. However, it does not explicitly state when not to use this tool versus siblings, though differentiation is implicit due to unique functionality.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing what the returned profile contains (contact info, resume, interview history, status). No contradictions.

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

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

Single sentence, no wasted words. Directly states purpose and return content. 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?

Given the tool is a simple get-by-ID with a known output schema, the description together with annotations and schema provides complete context. No missing information for an agent to use it correctly.

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

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

Schema coverage is 100% and both parameters (_apiKey and candidateId) are fully described in the schema. The description does not add additional semantics beyond stating 'by ID', 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 action (Get full candidate profile by ID) and lists the specific data returned (contact info, resume, interview history, current application status). It distinguishes from siblings like ashby_list_candidates and ashby_get_job.

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

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

The description implies when to use (when you need a complete candidate profile by ID) but does not provide explicit guidance on when not to use it or mention alternative tools like ashby_list_candidates for listing candidates.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying what the tool returns (description, requirements, hiring stage, applicant count) beyond what annotations provide. No contradictions.

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

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

Two sentences, front-loaded with verb and resource, no redundant words. Every part 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?

For a simple get-by-ID tool with rich annotations and an output schema, the description provides the necessary context about return fields and purpose. 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 description coverage is 100%, so the schema already documents both parameters (jobId and _apiKey). The description does not add additional meaning beyond 'by ID', so it meets the baseline.

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

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

The description clearly states the verb 'Get' and resource 'full job posting by ID', and lists specific returned fields (description, requirements, hiring stage, applicant count). It distinguishes from siblings like ashby_list_jobs which is for listing, and other tools.

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

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

The description implies use when you have a job ID and want full details, but no explicit when-not or alternative tools are mentioned. Among siblings, ashby_list_jobs exists for listing jobs but is not referenced.

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, so no contradictory information. Description adds specific output fields (candidate name, job, stage, date) which is helpful beyond annotations.

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

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

Single sentence with clear purpose and output list. No wasted words, front-loaded with action and result.

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?

Has output schema, so description need not detail return format. Description provides a brief summary of return fields. Could mention pagination or filtering, but given openWorldHint and simplicity, it is adequate.

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 description does not need to add parameter details. The description does not elaborate on cursor or per_page parameters, but schema already defines them well, meeting the baseline.

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

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

Description clearly states it searches job applications and lists returned fields. However, it does not explicitly distinguish from sibling tools like ashby_list_candidates or ashby_list_jobs, missing a chance to differentiate.

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

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

No guidance on when to use this tool versus alternatives. No exclusions or context provided, leaving the agent to infer usage without additional clarity.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it returns names, emails, and application metadata, but omits pagination behavior (cursor/per_page are in the schema but not described in the description). With solid annotation coverage, a 3 is appropriate as the description adds some context without overdelivering.

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

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

The description is two sentences: the first clearly states the tool's purpose and return value, the second names the alternative tool. No extraneous words; every sentence earns its place.

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

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

The tool has an output schema (not shown but indicated), so the description need not detail return structure. It says it returns names, emails, and application metadata, which covers the main output. The input schema shows only cursor and per_page, no filters, so the description could clarify that this is a list rather than a full search with filters, but the schema makes that implicit. Overall, it's fairly complete for a list 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%—all three parameters (cursor, _apiKey, per_page) have descriptions in the schema. The description does not add any parameter-level semantics beyond what the schema already provides, so the baseline score of 3 is warranted.

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 ('Search') and resource ('candidates in your ATS'), and distinguishes itself from the sibling tool 'ashby_get_candidate' by noting that it returns names, emails, and application metadata while the sibling provides full profile 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?

The description states the tool is for searching candidates, and explicitly directs users to 'ashby_get_candidate' for fuller details, providing clear context on when to use each. It doesn't explicitly mention when not to use it, but the sibling contrast gives sufficient 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 read-only and idempotent behavior. The description adds that it returns job title, department, and posting details, and specifies filter values, which are useful beyond annotations.

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

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

Two concise sentences with no wasted words. Purpose is front-loaded and each sentence adds value.

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

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

Given annotations and output schema (existing), the description covers purpose and output. Lacks details on pagination or ordering but is complete for a simple list tool.

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

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

Schema coverage is 100% so descriptions already explain parameters. The tool description repeats the filter values but adds no new parameter semantics 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 searches open positions with filtering by status, and specifies return fields. It distinguishes from sibling tools like ashby_get_job by implying a list operation, but lacks explicit 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 provides no guidance on when to use this tool versus alternatives like ashby_get_job for single job details. Usage context is implied but not explicit.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds context by clarifying it routes to 3,826 tools, fills arguments automatically, and returns structured answers with pipeworx:// 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?

Description is relatively long but front-loaded with key preference and usage guidance. Every sentence adds value, though some repetition (e.g., list of sources) could be slightly condensed. Overall efficient.

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

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

Given no output schema, description fully explains return value (structured answer with citation URIs). Input schema covers all parameters with examples. Complete coverage for a complex query 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 clear descriptions and aliases (q, text, input, query, prompt). Description adds examples in the schema but no additional semantic info beyond what schema provides. Baseline 3; slight elevation due to rich examples.

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

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

Description clearly states it answers factual questions using authoritative structured data with citations. Distinguishes from web search and sibling tools like deep_research by emphasizing preference for current/historical data from 3,826 tools across 912 sources.

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 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance with examples of queries (e.g., 'current US unemployment rate', 'Apple's latest 10-K'). Also lists trigger phrases like 'what is', 'look up', 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?

Beyond annotations indicating read-only, open-world, idempotent, and non-destructive, the description adds behavioral traits: extra LLM call cost, refusal reasons (not_in_source, no_tool_match, etc.), and the exact return structure on success and failure. 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 concise, front-loading the core purpose and key behaviors, and delivers all necessary information in a few sentences without redundancy.

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

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

Despite lacking an output schema, the description fully compensates by detailing the return structure and all possible refusal reasons. Given the tool's complexity and high-stakes use, it provides complete contextual information for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with descriptions for all parameter aliases. The description adds no additional parameter semantics beyond what the schema already provides, resulting in a baseline score of 3.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and details its process of tool selection, data fetching, and extraction strictly from tool results. It distinguishes itself from the sibling 'ask_pipeworx' by being more rigorous and costlier.

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

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

Explicitly advises use when answers will be quoted, cited, or acted upon, and the agent must not invent facts. Also recommends preferring 'ask_pipeworx' for casual lookups, 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?

The description extensively details behavioral traits beyond annotations: it covers fan-out logic, response shapes, low-confidence match handling, closed market detection, wide-spread warnings, resolution-rule risk, and fallback mechanisms. All annotations (readOnlyHint=true, etc.) are consistent and no contradictions exist.

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

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

The description is verbose and packed with technical details, which is informative but lacks conciseness. It is structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.), but could be shortened without losing essential information.

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

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

Given no output schema and moderate complexity (3 params), the description is remarkably complete. It explains every part of the response, edge cases (429s, closed markets, low confidence), resolution rules, and safety mechanisms. Nothing critical is missing.

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

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

Schema description coverage is 100%, but the description adds significant value by explaining how different input types are handled (slug vs URL vs question text), providing examples, and detailing the depth parameter's effect. This goes 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 it researches a Polymarket bet by pulling Pipeworx data, accepts multiple input types (slug, URL, question text), and returns an evidence packet with comparison. It provides usage examples like 'should I bet on X' but does not explicitly differentiate from sibling tools such as polymarket_edges or polymarket_arbitrage, though the purpose is specific.

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

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

The description explicitly lists use cases ('Use for "should I bet on X"...') and explains when the tool is appropriate. It lacks explicit when-not-to-use guidance or alternatives, but the provided scenarios are clear enough for an agent to decide.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint correctly. The description adds significant behavioral context: it makes a single parallel call, handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. 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 densely packed with useful information. It is front-loaded with example queries. Every sentence provides value, though it could be slightly more concise without losing clarity. The structure is logical: examples, preferred usage, parameter details, behavioral notes.

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

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

Given the complexity (2 entity types, multiple data sources) and no output schema, the description does a good job explaining what is returned (paired data, citation URIs) and how results are sorted. It could optionally describe the exact response structure, but the listed metrics (revenue, net income, etc.) give adequate context. Overall, it is sufficiently complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds meaning beyond the basic schema: it explains the enum values for type, what data each pulls, and how to format values (tickers vs drug names). It also clarifies the max and min items for the values array, enhancing the schema's descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides natural language examples and specifies data sources (SEC EDGAR/XBRL for companies, FAERS/drug data for drugs). It distinguishes itself from sequential single-pack lookups, which is a strong differentiator.

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

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

The description explicitly advises to prefer this tool over sequential lookups when comparing entities. It explains when to use the 'company' vs 'drug' type and what metrics are compared. It does not explicitly mention when not to use it or alternative tools, but sibling tools like entity_profile or deep_research could be inferred as alternatives for deeper dives.

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, etc. Description adds rich behavioral detail: question decomposition, parallel execution, evidence with citations, gaps array, and time expectations. No contradictions.

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

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

Well-structured and front-loaded with core value. Some redundancy (e.g., 'in ONE call' and 'IN PARALLEL') but every sentence adds value. Slightly verbose but efficient for complexity.

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

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

Comprehensive for a complex multi-step tool. Describes output format (findings packet with evidence, confidence, source, gaps), alternatives, prerequisites, and performance expectations. No output schema, but description compensates.

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

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

Input schema has 100% description coverage. Description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8) and provides examples for the question parameter.

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

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

Description clearly states 'Grounded multi-source research in ONE call' and explains decomposition, parallel routing, and structured output. It distinguishes from sibling ask_pipeworx by noting single vs. multi-part questions.

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 recommends for broad/multi-part questions with examples, and advises using ask_pipeworx for single lookups. Also mentions account requirements and depth limitations.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds that it returns top-N relevant tools with full schemas and curated examples, and that results are ready to call. No behavioral contradictions.

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

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

The description is a single paragraph that quickly states the purpose, provides when-to-use guidance, and describes output. It is front-loaded and efficient, though could potentially be slightly more 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?

Given no output schema, the description adequately explains what is returned (names, descriptions, schemas, examples). It covers the main use case and output format well, though it could mention that output includes curated examples explicitly.

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

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

Schema already describes all 6 parameters with 100% coverage. Description adds value by listing example queries ('look up FDA drug approvals') and mentioning aliases, and by suggesting domains (SEC filings, etc.) which guide query formulation.

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 finds tools by describing the data or task, distinguishing it from sibling tools that perform specific tasks. It emphasizes that it returns full schemas and examples, making it ready to call directly.

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: 'browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Implicitly suggests not to use when the tool is already known. Lacks explicit 'when not to use' but given clear context, it is adequate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral details: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), mentions USPTO soft-failure after May 2025, specific return fields, and the one-call parallel nature. 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 appropriately sized given the tool's complexity. It front-loads example user queries that mirror agent invocation patterns. Every sentence provides unique value, with no redundancy or filler. It is structured to quickly convey purpose, usage, and behavioral nuances.

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

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

Despite no output schema, the description thoroughly enumerates the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers sources, timeframes, fallback behaviors, and limitations. For a tool with only two parameters, the description is 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 coverage is 100%, and the description adds substantial meaning beyond the schema: it clarifies that value can be a ticker or CIK (with example), explicitly states names are not supported and to use resolve_entity first, and explains the type parameter is currently limited to 'company'. This enriches the static schema definitions.

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 action phrases like 'Tell me about X', 'research Acme', and clearly states it produces a full cross-source profile of a US public company in one parallel call. It distinguishes from sibling tools such as 'resolve_entity' by noting that names are not supported and that this tool should be preferred over chaining single-pack lookups for holistic views.

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 this tool ('ALWAYS PREFER over chaining single-pack...lookups when the user asks for a holistic view') and when not to ('names not supported — use resolve_entity first if you only have a name'). Provides clear context about the tool's role relative to alternatives.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale contexts, going beyond annotations without contradiction.

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

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

Two sentences, zero waste. First sentence gives purpose, second gives usage guidance and sibling references. Highly efficient.

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

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

Given the tool has one parameter and no output schema, the description is complete: it explains what the tool does and when to use it. No gaps remain.

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

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

Schema coverage is 100% with a single parameter 'key' well-described as 'Memory key to delete'. The description adds no extra parameter info beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key', using specific verb (delete), resource (memory), and method (by key). It differentiates from siblings like remember and recall.

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: 'context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall for related operations.

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. The description adds valuable detail: it fetches the page, extracts title/description/key links, and outputs standard markdown. 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 a single paragraph that front-loads the core purpose. It is concise with no redundant sentences, but could be slightly more structured (e.g., bullet points for use cases). Still efficient.

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

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

Despite lacking an output schema, the description explains the output format (standard llms.txt markdown, single blob for site-root/llms.txt). Parameter behavior is covered, and the tool's function is fully described for an agent to use it 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%, so the schema already documents both parameters. The description does not add new meaning beyond what's in the schema (e.g., the default and max for max_links are in the schema). Baseline 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for AI crawlers, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes from sibling tools like ai_visibility_check by focusing on file creation rather than 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 provides explicit use cases (client sites, personal projects, competitor auditing) but does not mention when not to use or suggest alternatives. Still, the context is clear enough for an agent to decide, earning a 4.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive nature. Description adds no further behavioral traits beyond what annotations provide, so a 3 is appropriate.

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 wasted words. Efficiently conveys purpose, return data, and use case.

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

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

Given the simple tool with one optional parameter and no output schema, the description is complete: it states what it lists, what it returns, and when to use it.

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

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

Parameter include_inactive is fully described in the schema (100% coverage). The description does not add additional meaning beyond the schema, so baseline 3.

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

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

Description clearly states verb 'List', resource 'the caller's active subscriptions', and specifies the returned fields. Differentiates from siblings like subscribe and unsubscribe by implying it's for reviewing existing subscriptions.

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

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

Explicitly advises using this tool 'before adding more' subscriptions or 'to find an id to cancel.' Provides clear usage context though doesn't mention alternatives beyond the implied sibling tools.

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

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

Beyond annotations (which are all false), the description reveals important behaviors: it's free and doesn't count against tool-call quota, rate-limited to 5 per identifier per day, and the team reads digests daily. This provides significant context about impact and constraints.

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

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

The description is moderately long but every sentence adds value. It starts with the core purpose, then practical usage, then constraints, and ends with key facts (rate limit, quotas). No fluff or redundancy.

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

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

Given the simplicity of the tool (3 params, no output schema), the description completely covers what an agent needs to know: when to use, how to structure feedback, rate limits, and how the feedback is processed. Nothing is missing.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds extra semantic value: it further clarifies the 'type' enum values, emphasizes specificity in 'message', and explains the optional 'context' object. This goes beyond the schema alone, earning a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, which are all other functionality (search, entities, etc.), making its unique purpose evident.

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 provides when-to-use scenarios: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives explicit guidance on what not to do: 'don't paste the end-user's prompt,' and explains how feedback is used, making it highly actionable.

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

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

Annotations already declare safe, idempotent, read-only nature. Description adds context: self-aggregating signal from CF analytics-engine, no PII, caching behavior (5min-1h). No contradictions.

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

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

Two paragraphs with bullet-like use cases; front-loaded with main output. Could be slightly tighter but no wasted sentences.

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

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

Fully explains output composition, caching, and privacy for a single-param optional tool. No output schema needed given context.

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

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

Schema covers 100% with enum description. Description adds behavioral nuance: shorter windows surface hot trends, longer windows show steady-state demand, adding value beyond schema.

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

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

Explicitly states it returns top tools, top packs, and total call volume over a recent window, using specific verbs and resources. Distinguishes from siblings like 'discover_tools' by focusing on trending data.

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

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

Provides three concrete use cases (discovering hot data sources, confirming popular tool, aligning use case). Lacks explicit exclusion criteria but 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?

The description discloses numerous behavioral traits: required parameters, error conditions for empty calls, internal checks (Jaccard similarity, partition filter, fill check), and specific conditions like 'skipped_low_similarity surfaces the rejected pair count.' All align with annotations (readOnly, idempotent). No contradictions.

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

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

The description is front-loaded with the key requirement and is well-organized into sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). However, it is quite verbose and could be slightly more concise without losing detail.

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

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

Given the tool's complexity (two modes, multiple checks, no output schema), the description thoroughly covers all aspects: inputs, outputs (opportunities[], partition_check, fill_check), error conditions, and references to sibling tools. It leaves no major gaps.

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

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

Schema coverage is 100%, and the description adds significant meaning: explains each parameter's role, gives example values, and details the behavior of event vs. topic modes. It goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges and 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?

The description provides explicit guidance on when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning).' It also warns that 'call with no args fails' and points to polymarket_fill_risk for custom sizing, offering clear context for usage.

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

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

The description adds substantial behavioral context beyond annotations. It explains the output structure (by_segment, fed_candidates, diagnostics), the model families in detail, the caching policy (1h at KV level keyed on all knobs), and the Fed bets exclusion rationale. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, and the description aligns perfectly without contradiction.

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

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

The description is quite verbose (over 500 words) and dense with technical details, which may be overwhelming. However, it is well-structured with headings (FIVE MODEL FAMILIES, TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) and front-loads the core purpose. The level of detail is justified given the tool's complexity, but it could be trimmed for conciseness.

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

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

Given the tool's 9 parameters, no output schema, and no nested objects, the description provides extensive detail on the output structure, including segments (model_driven, structural_arbitrage, concentrated_longshot), diagnostic information, and cache policy. It covers filters, edge calculations, and why certain segments might be empty, making it fully complete for an AI agent to understand and use the tool effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining tradeable-edge knobs (min_liquidity, max_spread_pp) in the context of the tool's logic, but it does not significantly enhance individual parameter descriptions beyond what the schema already provides. The parameter meanings are clear from 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 it scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly calls out the tool's purpose as 'what should I bet on today,' providing a specific verb and resource. While it doesn't directly differentiate from siblings like polymarket_arbitrage, the detailed explanation of model families (model_driven, structural_arbitrage, concentrated_longshot) implicitly distinguishes its broader 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 states the tool is for discovering opportunities without paging hundreds of markets, giving clear context for when to use. It also mentions tradeable-edge knobs (min_liquidity, max_spread_pp) that help filter unrealizable edges. However, it does not explicitly state when NOT to use this tool versus alternatives like polymarket_arbitrage or polymarket_kalshi_spread, missing a direct exclusion statement.

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

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

The description adds significant behavioral context beyond annotations, including details on data gaps (snapshots written on cache-miss, gaps mean no scans), decay computation from daily closes (not intraday), and the meaning of edge_pp_net sign. Annotations already declare readOnly, idempotent, non-destructive; description aligns and enriches.

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

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

The description is front-loaded with the main purpose and structured with clear output sections (tracked[], expired[], snapshot_dates[]). Some colloquial phrasing ('wide for a reason nobody is willing to take') adds character but is not strictly necessary. Overall, it is informative without being excessively 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?

Given the lack of an output schema, the description does a good job explaining the return structure and fields (e.g., edge_pp_net time-series, trend, decay_pp_per_day). It covers data availability, expiration, and limits. Minor missing details like pagination or result limits are not critical.

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 detailed descriptions. The description repeats defaults and adds explicit max 30 for days, slightly clarifying the clamp range. No new parameters are introduced. Baseline 3 is appropriate as the description adds minimal value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It specifies the exact question answered and distinguishes outputs (tracked, expired, snapshot_dates). This differentiates it from related tools like polymarket_edges, which likely provides current snapshots only.

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 context, such as answering how long an edge has existed and whether it is shrinking, with an example contrasting fresh vs. old wide edges. It also mentions limits (60-day TTL, snapshot start date). However, it does not explicitly state when not to use the tool or directly compare to sibling tools.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context on top of that, explaining that the tool performs a check and returns verdicts (clean, degraded, cannot_fill), that it walks the order book ladder, and warns that partial fills are dangerous. No contradiction with annotations.

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

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

The description is relatively long but well-structured with bold headings for modes and key details. It contains necessary risk warnings and output field lists. Every sentence adds value, though some details could potentially be moved to output schema if it existed. Still, it is appropriately dense for a complex tool.

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

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

Given the tool's complexity (dual modes, 4 parameters, no output schema), the description is remarkably complete. It explains all outputs (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; and for basket: theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). It also covers edge cases like thin legs and directional risk.

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 adds value by explaining the meaning of size_usd in different modes (max spend on buys, target proceeds on sells for single-market; settlement notional for basket) and default auto behavior for side. It does not simply repeat schema but provides operational context.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-execution risk 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 explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains when not to use it, citing that theoretical overround on thin books is not capturable and partial basket fills convert an arb into a directional position.

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

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

The description goes far beyond annotations by detailing compatibility_warning triggers (non-equivalent bet shapes, no token overlap), temporal_alignment checks, and skipped cross-type/subtype counters. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. However, it is verbose and could be trimmed slightly without losing necessary detail, earning a 4 rather than 5.

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

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

Given the complexity and lack of output schema, the description thoroughly explains the response format (leg-by-leg prices, matched spreads, safety fields) and edge cases (compatibility_warning conditions, temporal alignment). 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?

Schema coverage is 100%, so the schema already describes each parameter. The description adds value by listing the valid topic shortcuts and clarifying that explicit tickers override topic-mapped sides. This is helpful but not fully compensating for the lack of enum constraints.

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

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

The description clearly defines the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes ('topic' shortcuts and explicit tickers) and describes the output structure. This distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides explicit guidance on when to use each mode, including the caveat that most pre-mapped topics currently return compatibility warnings. It explains the conditions under which the tool is useful and when it will indicate non-tradeable spreads.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it recalls data saved via remember and is scoped to the agent's identifier, which is useful context beyond annotations.

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

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

Three sentences, each adding essential information: functionality, purpose with examples, and scoping. No redundant words, front-loaded with the primary action.

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

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

Given the tool's simplicity (single optional parameter, no output schema), the description fully covers what the tool does, when to use it, and how to use it (including the alternative of omission).

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 'key'. Description adds meaning by explaining that omitting the key lists all saved keys, which is not explicitly stated in the schema.

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

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

Clearly states it retrieves a saved value or lists all keys, with explicit reference to the sibling tool 'remember' and use cases like 'user's target ticker' or 'prior research notes'. Distinguishes from siblings by naming them.

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

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

Describes when to use (look up stored context without re-deriving) and scoping (by identifier). Does not explicitly list when not to use, but the pairing with remember/forget provides implicit 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, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations, such as the effect of mark_read (flagging events as read so next call shows newer ones) and the note that polls work fine. 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 concise (3-4 sentences) and front-loaded with the main purpose. Every sentence provides essential information: what it does, what each item carries, filtering options, and usage notes. No fluff.

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

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

Given no output schema, the description adequately explains the return value (source, citation_uri, payload). It covers all parameters, filtering, and practical considerations (polls, alternative endpoint). The tool is read-only with 0 required parameters, so the description is complete enough for effective use.

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

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

Schema coverage is 100%, so the baseline is 3. The description provides an example for type ('sec_8k') and explains mark_read behavior, but the schema already describes each parameter adequately. The description adds marginal value beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts. It specifies the verb ('pull', 'returns') and resource ('your subscription feed'), and the details about source, citation_uri, and payload make it distinct from sibling tools like list_subscriptions or subscribe.

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

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

The description mentions that polls work fine and provides an alternative HTTP endpoint for scripts/dashboards, giving context on when to use this tool vs other access methods. However, it does not explicitly compare to other sibling tools like recall or search_within, which could be alternatives for similar data retrieval tasks.

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 a safe read operation, and the description adds significant behavioral context: it fans out to three sources (SEC, GDELT→GNews, USPTO), explains the PatentsView sunset soft-fail, and specifies the return structure (changes grouped by source, total_changes count, citation URIs). No contradictions with annotations.

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

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

The description is relatively long but every sentence adds value. It front-loads example queries and uses a block format to explain each source. Could potentially be slightly more structured, but it remains functional 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?

Given the tool fans out to multiple data sources with fallback logic and no output schema, the description thoroughly documents the return structure (changes[] grouped by source, total_changes, citation URIs) and behavioral constraints (PatentsView sunset, GDELT→GNews fallback). All critical aspects are covered.

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

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

Input schema has 100% description coverage, but the description adds clarifying examples for the 'since' parameter (ISO date vs relative shorthand like '7d', '30d', '3m', '1y') and explains that 'value' can be a ticker or zero-padded CIK.

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 example natural language queries, defines the tool as a 'change feed for a company in the last N days/weeks/months', and explicitly distinguishes itself from sibling tool entity_profile ('Use entity_profile instead when you want the static profile...').

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

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

The description provides clear when-to-use guidance with example queries and explicitly names the alternative tool entity_profile for static profile requests. It also explains fallback behavior between GDELT and GNews, and notes PatentsView API limitations.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds key behavioral context: memory is key-value scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. No contradictions.

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

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

The description is front-loaded with the core purpose and provides additional context in a few clear sentences. It is not overly verbose, though it could be slightly more concise.

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

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

For a simple key-value memory tool with no output schema, the description covers purpose, usage, persistence behavior, and sibling tools (recall, forget). It is fully informative for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with parameter descriptions for 'key' (with examples) and 'value'. The description adds the context of scoping and persistence but does not significantly extend parameter semantics 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 'Save data the agent will need to reuse later' and provides concrete examples like 'resolved ticker, target address, user preference'. It distinguishes from sibling tools by mentioning pairing with recall and forget.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and explains persistence differences for authenticated vs. anonymous users. It does not explicitly say when not to use, but 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?

The description adds significant behavioral context beyond the annotations, such as internal cascading through multiple lookup endpoints and the specific return fields (ticker, CIK, RxCUI, citation URIs). No contradiction with annotations.

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

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

The description is a single paragraph but packs essential details without verbosity. It front-loads with examples. However, it could be slightly better structured (e.g., bullet points for types) to improve readability.

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

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

Given the lack of output schema, the description adequately covers return values for both entity types, including citation URIs. It also notes auto-disambiguation for companies. However, it omits edge cases like ambiguous inputs or error handling.

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

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

With 100% schema coverage, the description adds value by clarifying input formats (e.g., 'AAPL', '0000320193' for company) and explaining that company accepts multiple input types (ticker, CIK, name) while drug accepts brand or generic name. This goes beyond the brief 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 identifies the tool's purpose: resolving user-spoken names to canonical identifiers. It provides specific examples (ticker, CIK, RxCUI) and distinguishes itself from siblings by stating it replaces 2-3 manual lookups.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear context. It explains supported types (company, drug) and input formats. However, it does not explicitly state when not to use this tool 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?

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It does not mention rate limits, API key requirements for anthropic models, or potential costs, but these are partially covered by the schema.

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: purpose, method, use case and output. No unnecessary words, front-loaded with the primary action, and structured for quick understanding.

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

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

Given no output schema, the description explains the return value (ranked list with score, confidence, signal density). It covers the key outcome. It does not specify edge cases (e.g., invalid entities, model unavailability) but is complete for typical use. Score 4 for adequate coverage.

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 all parameters have descriptions. The tool description does not add significant new meaning beyond the schema; it only reiterates that entities should include the subject and competitors. Baseline score of 3 is appropriate.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check as a sub-tool. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the AI visibility context and ranking 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?

The description gives a use case ('competitive AI-marketing audits') and an example question, implying when to use it. However, it does not explicitly state when not to use it (e.g., when only a single entity check is needed) or contrast with alternatives like ai_visibility_check.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds valuable behavioral context: composite fan-out across services, graceful degradation with potential 5-30s delay on first measurement, and the sources_failed reporting mechanism. 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 front-loaded with the core purpose, then systematically covers services used, usage examples, return values, limitations, and edge cases. Every sentence adds value; no redundancy or unnecessary detail.

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

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

Despite lacking an output schema, the description fully explains the return structure (summary block, per-advisory detail, links, alternative versions) and covers partial failures, timeouts, and ecosystem scope. It provides sufficient context for an agent to understand 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?

Schema description coverage is 100% with both parameters well-documented (package accepts scoped, version defaults to latest). The description does not add significant new semantic meaning beyond the schema, so baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a composite check for npm packages, specifying the verb (check), resource (npm package), and the covered aspects (license, advisories, version history, bundle size, etc.). It distinguishes from sibling tools by noting NPM-only scope and referencing alternatives for other ecosystems.

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 provided via examples like 'is X safe / popular / small' and 'what does adding lodash cost me'. Limitations are stated (NPM only v1) with clear alternatives (deps.dev:version for PyPI/Maven/Cargo/Go). Partial failure handling is also described.

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=false. The description adds valuable behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character cap (200K with truncation), and that passages carry offsets for verification. This significantly enriches 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 compact and efficient, with no wasted words. It front-loads the core purpose, then provides technical details and pairing advice. Every sentence earns its place.

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

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

Despite no output schema, the description explains return values (top-N passages with character offsets and similarity scores) and truncation behavior. All aspects of the tool's operation are covered clearly.

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 description need not repeat schema. However, it adds useful context: text parameter max size, limit range and default, and natural-language examples for query. This adds value beyond the schema, though not exceptional.

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

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

The description clearly states it performs semantic search inside a fetched record, using specific verbs and resources ('search inside a fetched record'). It distinguishes itself from sibling tools like ask_pipeworx_grounded by explaining when to use each.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, providing clear guidance on when to use this tool versus alternatives.

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

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

The description adds behavioral details beyond annotations: it returns a subscription id, requires OAuth, lists supported types with param examples, and details delivery channels with constraints (SMS cap, webhook auto-disable, email/sms/phone verification). Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false) are consistent and complemented by these specifics.

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 front-loaded with the core purpose. It uses clear sentences and examples. While slightly verbose, every sentence adds essential information. Could be slightly more structured with bullet points, but the narrative format works.

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

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

Given the complexity (3 parameters, 5 types, nested objects, no output schema), the description covers the return value, prerequisites, type-specific params, and delivery details. It does not explain error cases or response format fully, but the idempotent hint and examples compensate.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond field names: it explains type-specific param formats (e.g., sec_8k requires items codes), required vs optional fields, and constraints (e.g., webhook HTTPS only). This adds value beyond the schema's property 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 it creates a proactive monitoring subscription to a live-data event stream. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation. The verb 'create' and resource 'subscription' are specific, and examples of types and delivery channels provide further clarity.

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

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

The description explicitly mentions when to use (to subscribe to alerts), prerequisites (Pipeworx OAuth account; anonymous/BYO cannot persist), and delivery options. It does not explicitly state when not to use or provide alternatives, but the context of siblings (e.g., ask_pipeworx for one-time queries) is implied.

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. The description adds context about being an onboarding tool, returning examples from a live catalog, and focusing on meta-tools, 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 well-structured and front-loaded with purpose, though slightly lengthy with the list of categories. Still clear and concise overall.

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

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

Given the simple tool (1 optional param, no output schema), the description fully covers when to use it, what to expect, and how to call it.

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

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

Schema coverage is 100% for the single optional parameter. The description adds meaning by listing possible values and explaining that omitting topic gives a full spread.

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 an onboarding agent, distinguishing it from siblings like 'ask_pipeworx' and 'entity_profile'.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides guidance on using the optional 'topic' parameter.

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 critical behavioral details beyond the annotations: ownership enforcement, deactivation instead of deletion, and historical availability via recent_alerts. This is not covered by the annotations header, which only hint at idempotence and non-destructiveness.

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

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

The description is extremely concise, using only two sentences to convey the essential information without waste. It is front-loaded with the key action.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is fully complete. It explains ownership, the nature of cancellation, and post-cancellation 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?

The input schema already provides full coverage for the single parameter 'id' with a description. The tool description does not add further value to the parameter semantics, meeting the baseline expectation.

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

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

The description uses a specific verb ('Cancel') and resource ('subscription'), clearly indicating the tool's action. It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by detailing the effect (deactivation, not 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 states when to use the tool (to cancel a subscription). While it does not explicitly mention when not to use it or list alternatives, the context is clear enough for a simple operation.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: returns a verdict with specific types, includes citation, and states 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 moderately concise and front-loaded with example queries. It efficiently communicates purpose, scope, and output. A minor length reduction could improve, but overall well-structured.

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

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

Given the tool has only one parameter and no output schema, the description covers the key aspects: input expectations, supported domain, and output structure (verdict types, citation). The annotations further enrich completeness. No significant gaps.

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

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

The single parameter 'claim' is well-described in the schema with examples. The description adds further semantic clarity by detailing the natural-language nature and providing concrete examples of valid claims. Schema coverage is 100%, so the description enhances rather than compensates.

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 like 'validate', 'fact-check', 'verify', and clearly distinguishes the tool's purpose for natural-language claim verification against authoritative sources. It provides multiple example queries and specifies the scope (company-financial claims). No sibling tool duplicates this functionality.

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?

States explicitly to use 'whenever the agent needs to check whether something a user said is factually correct'. Mentions supported claim types (company-financial). Does not explicitly mention when NOT to use, but the scope is clear. Lacks explicit alternatives, but the context is sufficient.

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