Tfl

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by explaining the default model, optional Anthropic probe with BYO key and direct billing, and return format. 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 three sentences, each serving a distinct purpose: core function, parameter details, and use cases. No extraneous words, and key information is front-loaded. 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?

Despite no output schema, the description explains the return format (per-model score, confidence, signals, raw_response + combined view). It covers all parameters and their roles. Missing details like error handling or rate limits are acceptable given the tool's simplicity and annotation 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 baseline is 3. The description adds context beyond schema: it explains the default model for 'models' parameter, the dependency of '_apiKey' on including 'anthropic' in models, and the purpose of 'context' for disambiguation. This enriches understanding.

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

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

The description clearly states the tool probes LLMs for visibility of an entity and outputs a score (0-100). It uses specific verbs ('probe', 'score') and resource ('visibility per model'), and distinguishes from siblings by focusing on LLM awareness, not generic scanning.

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

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

The description provides use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') that indicate when to use it. However, it does not explicitly mention when not to use it or compare to alternatives like 'scan_competitor_ai_presence', leaving some room for ambiguity.

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

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

Annotations already indicate the tool is read-only (_readOnlyHint: true_), non-destructive, and idempotent. The description adds that results are real-time, predicted, and sorted by timeToStation (nearest first). This adds moderate additional value beyond the annotations.

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

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

The description is extremely concise with three short sentences. The first sentence immediately states the tool's core purpose, followed by essential usage details. Every sentence adds value, and there is no superfluous information.

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

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

Given the tool's simplicity (one parameter, clear annotations, no output schema), the description covers input source and output sorting behavior. It does not explicitly describe the return structure, which could be a minor gap, but overall it provides sufficient context for an agent to 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?

The input schema description for naptanId states 'Stop NaPTAN id, obtained from stop_search.' The tool description reinforces this with a concrete example ('940GZZLUOXC'), clarifying the parameter source and format. This adds meaningful context 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 that the tool provides 'Real-time predicted arrivals at a stop.' It distinguishes itself from the sibling tool 'stop_search' by specifying that the naptanId comes from stop_search, making the tool's role in the workflow unambiguous.

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

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

The description gives a clear usage instruction: 'Pass the naptanId from stop_search.' It provides an example and implies that the tool should only be used after obtaining a valid stop ID. While it does not explicitly list when not to use it or alternative tools, the context is sufficient for correct invocation.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds valuable context: routes to the correct tool among 4,819, fills arguments, returns structured answers with citation URIs, and works on all tiers.

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 directive and well-structured with examples and alternative guidance. While lengthy, every section serves a purpose.

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

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

Given the tool's complexity (routing to many sources), the description is comprehensive: covers purpose, usage, examples, and alternatives. No output schema needed as return format is explained.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the 'question' parameter accepts natural language and listing aliases. Examples further clarify usage.

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: to answer factual questions using authoritative structured data from thousands of sources, routing to the appropriate tool. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. Provides clear when-to-use and when-not-to-use guidance, including specific alternatives for more focused or broader queries.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details the return shape including evidence, confidence, and refusal reasons, and explains the extraction-only behavior. No contradictions with annotations.

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

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

The description is a single, dense paragraph that delivers essential information upfront. While it contains necessary details, it could benefit from slight restructuring for readability, but no superfluous content.

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

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

Given the tool's complexity (high-stakes, refusal handling, evidence extraction), the description covers purpose, usage context, behavioral details, return format, and cost trade-off. No output schema is provided, but the description fully compensates.

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

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

The input schema has 6 parameters, all aliases for 'question', each described as such. Schema coverage is 100%, so the description adds no additional meaning beyond that the question is used for routing, which is already implied.

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

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

Description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from the sibling ask_pipeworx by specifying that it extracts answers only from tool results and provides explicit refusal reasons when the data is insufficient.

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

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

Provides explicit guidance: use when answers will be quoted, cited, or acted on, and when the agent must not invent facts. Also advises preferring ask_pipeworx for casual lookups due to additional cost.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral detail: fan-out mechanisms, response shapes, low-confidence short-circuit logic, closed market handling, wide-spread tradeability notes, cancellation rule parsing, and resolution contract inspections. No contradictions with annotations.

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

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

The description is well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. It is verbose but every sentence adds value given the tool's complexity. Slight trimming could improve conciseness without losing critical details.

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

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

The description covers all critical aspects: input handling, resolution logic, classification, parallel fan-out, response shapes, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety. No output schema exists, so the description fully compensates by detailing return fields and their interpretations.

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?

Schemas provide 100% description coverage, but the description adds practical meaning: explains market input formats (slug, URL, question), depth options (quick vs thorough), and include_raw purpose ('keeps responses under ~20KB'). This enriches the agent's understanding beyond the schema.

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

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

The description begins with a clear verb-resource pair: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and the tool's actions (resolve, classify, fan out, compare). This clearly distinguishes it from siblings like polymarket_arbitrage or polymarket_edges, which serve different purposes.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also warns about times to be cautious (low-confidence matches, closed markets, wide spreads). However, it does not directly contrast with sibling tools or state when not to use it in favor of 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=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds that data is 'live', includes counts for bikes and empty spaces, and total capacity in 'additionalProperties'. No contradictions. Provides useful behavioral context beyond annotations.

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

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

Two sentences, no redundancy. First sentence delivers core functionality and return data structure; second sentence clarifies scope and parameter usage. Every word 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?

With only one optional parameter, no nested objects, and no output schema, the description fully covers what the tool does, what it returns, and how to use the parameter. Complete for a simple read-only data 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 parameter 'search' described. Description adds concrete example 'Clerkenwell' and clarifies it's an area filter. This enriches the schema's description, helping the agent understand valid inputs.

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

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

Description clearly states the tool provides live pushbike and empty-dock counts at London Santander Cycle hire docking points, with specific mention of 'additionalProperties' for total capacity. It uniquely identifies the resource and action, distinguishing it from siblings like 'arrivals' or 'disruptions'.

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 this is for London public bicycle rental only and provides example usage with optional area filter 'Clerkenwell' or omit for all docks. Could be improved by mentioning when not to use or suggesting alternatives for other transport modes, but current guidance is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds: pulls latest SEC EDGAR/XBRL data, handles off-calendar fiscal years, uses FAERS for drugs, sorts by primary metric, and returns citation URIs. 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 key phrases and structured with sections. It is slightly verbose (e.g., 'Replaces 8–15 sequential lookups') but every sentence adds value. Could be slightly trimmed but efficient.

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

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

There is no output schema. Description mentions 'paired data + citation URIs' and sorting, but does not detail exact fields returned for each entity type. For a comparison tool, this is adequate but not fully comprehensive.

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

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

Schema coverage is 100% with descriptions. The description adds examples (tickers vs drug names) and explains how type affects data sources and behavior, going beyond the enum and array schema.

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs' and lists trigger phrases like 'Compare X and Y' and 'rank these companies'. It distinguishes from siblings by advocating over sequential lookups and noting it replaces 8–15 queries.

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

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

The description gives clear when-to-use examples including natural language phrases and explicitly prefers it over sequential single-pack lookups. It does not explicitly state when not to use, but the scope is well-defined.

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. Description adds valuable behavioral context: account requirement, plan limitations, expected latency (15-60s), gap reporting, and that it returns stable pipeworx:// citations. 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 reasonably concise given the complexity, front-loading critical prerequisites (account requirement) and then explaining purpose and usage. Every sentence adds value, though some minor redundancy could be trimmed (e.g., repeating that it's not open-web search).

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 2 parameters, no output schema, and rich annotations, the description covers all necessary context: prerequisites, behavior, use cases, limitations, and latency. It is complete for an AI agent to make informed invocation decisions.

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 fully describes both parameters. The description adds semantic value by explaining depth values (quick=3, standard=5, thorough=8) and emphasizing that question should be natural language and broad/multi-part. This goes beyond schema descriptions.

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

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

The description clearly states the tool performs grounded multi-source research across 1259 structured data sources, decomposes questions, routes to tools in parallel, and returns a findings packet. It distinguishes from siblings like ask_pipeworx by highlighting its multi-call parallel research vs. single LLM call.

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

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

Explicitly states when to use (broad/multi-part questions over structured data), when not to use (single lookup, breaking/current news), and provides specific alternatives (ask_pipeworx, ask_pipeworx_grounded). Also mentions account requirements and depth plan restrictions.

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

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

Annotations already declare readOnly and idempotent. Description adds that results include full schemas with curated examples and are ready to call, which is useful behavioral context.

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

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

Front-loaded with purpose, then lists data categories, return behavior, and usage advice. Every sentence earns its place, though slightly wordy in listing categories.

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

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

Covers purpose, when to use, what returns (names, descriptions, schemas with examples). No output schema but description explains return structure. Adequate for a discovery tool.

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

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

Schema coverage is 100%. Description explains aliases for query (task, q, description, search) and provides examples, adding value beyond the schema.

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

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

Description clearly states 'Find tools by describing the data or task' and lists specific data categories. Distinct from sibling tools which are specific data or action tools.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that it returns 'current' data with 'description and affected lines,' which is useful but minimal 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, 12 words, no fluff. Every word is necessary and conveys the core purpose effectively.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the input and core output (disruptions with description and affected lines). However, it does not clarify the return format or handle potential edge cases, which is a gap given the lack of output schema.

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

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

Schema coverage is 100%—the only parameter 'modes' is well-described in the schema. The description adds no additional meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states it retrieves current disruptions for given transport modes, including description and affected lines. It is specific about the resource and action, though does not explicitly distinguish from sibling tools like 'line_status'—this is implied by the focus on disruptions.

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 (e.g., 'line_status' or 'arrivals'). The description lacks context for exclusion or prerequisites, leaving the agent without direction on tool selection.

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

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

Description adds significant behavioral context beyond annotations: it fans out across multiple sources, mentions patents soft-fail until May 2025, GDELT→GNews fallback, and details output URIs and ordering of fundamentals. 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?

Description is front-loaded with example queries, then states preference, then lists data sources. It is somewhat lengthy but every sentence adds value. Good structure with clear sections.

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

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

Without an output schema, the description fully explains return values: CIK, company name, recent filings with URIs, fundamentals, patents status, news fallback, LEI. It covers input constraints and special cases, making it sufficiently complete for a profile 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 has 100% coverage with descriptions for both parameters. The description reinforces that value can be ticker or zero-padded CIK, and that names are not supported, adding extra clarity beyond the schema. Baseline 3, plus added value gives 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 explicitly states the tool provides a full cross-source profile of US public companies, lists data sources (SEC, XBRL, USPTO, news, GLEIF) and outputs (CIK, filings, fundamentals, patents, news, LEI). It distinguishes from siblings by advocating preference over chaining single-pack lookups, and uses clear verbs like 'Tell me about', 'research', 'brief me'.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also specifies that names are not supported and advises using resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description simply restates 'Delete' without adding extra behavioral context (e.g., error behavior on missing key).

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

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

Two concise sentences that immediately state the action and usage context, with zero wasted words. Front-loaded with the core purpose.

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

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

For a single-parameter tool with no output schema and full annotation coverage, the description is fully sufficient: it specifies action, usage, and sibling relationships.

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 provides 100% coverage for the single parameter 'key' with a clear description. The tool description adds no additional meaning beyond what the schema already offers.

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 'Delete' and the resource 'previously stored memory by key', distinguishing it from sibling tools 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 lists three usage conditions ('context is stale, task is done, clear sensitive data') and pairs with remember and recall, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that it fetches the page, extracts content, and outputs a text blob, providing context beyond annotations.

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

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

Two sentences front-load the core action and add context with no wasted words.

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

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

Despite no output schema, the description explains the output format and what is extracted, making it sufficient for a two-parameter tool with good annotations.

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

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

Schema coverage is 100%, so the description adds no additional meaning beyond the schema-provided parameter 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 generates a 'llms.txt' file for any URL, specifically for AI crawlers, and distinguishes from sibling tools like 'ai_visibility_check' by focusing on the file generation 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 provides explicit use cases (client indexing, own project drafting, competitor auditing) but does not mention when not to use it or compare to other tools like 'scan_competitor_ai_presence'.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds value by specifying the output structure (lineStatuses and statusSeverityDescription), which enhances understanding of behavior beyond what annotations provide.

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

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

The description is concise with two well-structured sentences. It front-loads the purpose and efficiently conveys all necessary information without waste.

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

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

For a simple tool with two optional parameters and no output schema, the description is complete. It covers inputs, precedence, and output fields, leaving no ambiguity for agent invocation.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description repeats usage and adds precedence, but does not add significant new meaning beyond the schema.

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

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

The description clearly states the tool returns 'Current service status for London transport lines' with specific input options (modes or lineId) and output details (lineStatuses and statusSeverityDescription). It effectively distinguishes from sibling tools like arrivals or disruptions.

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

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

The description provides clear guidance on using either 'modes' or 'lineId', noting precedence for lineId. However, it does not explicitly compare with sibling tools or explain when not to use this tool.

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

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

Annotations already cover readOnly, idempotent, non-destructive. Description adds returned fields and default 'active' filter, but no edge cases.

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

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

Two concise sentences, front-loaded with purpose. No wasted words.

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

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

No output schema but lists returned fields. Lacks pagination info, but adequate for a simple list tool with annotations.

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

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

Schema covers 100% of one parameter with description. Description adds no extra parameter info beyond schema.

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

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

Clearly states verb 'list', resource 'subscriptions', and scope 'caller's active'. Mentions returned fields. Distinct from siblings like subscribe/unsubscribe.

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

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

Explicitly tells when to use: 'before adding more' or 'to find an id to cancel'. Implies alternatives, though not exhaustive.

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 a write operation (readOnlyHint=false) and description confirms sending feedback. The description adds value by disclosing rate limits (5 per identifier per day) and that the tool is free and doesn't count against quota. 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?

Description is well-structured and front-loaded with purpose. It uses concise sentences, each adding information about usage, behavior, and constraints. Slightly long but every sentence is justified; minor room for tightening.

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 100% schema coverage, no output schema, and 3 parameters (one nested), the description fully covers usage guidelines, behavioral traits, and constraints. No obvious gaps.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds extra meaning: it clarifies the type enum values with examples, explains the context object usage, and sets message length limits (2000 chars). This provides helpful context beyond the schema.

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

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

Description clearly states the tool sends feedback to Pipeworx team about bugs, features, data gaps, or praise. It uses specific verbs and distinguishes from sibling tools by focusing on feedback collection rather than data retrieval or actions.

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

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

Description explicitly lists when to use each feedback type (bug, feature, data_gap, praise) and provides a clear directive to avoid pasting end-user prompts. It also mentions rate limits and quota, though it does not explicitly contrast with sibling tools like ask_pipeworx.

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 context beyond annotations: self-aggregating signal, derived from CF analytics, no PII, caching behavior (5min-1h). This helps the agent set expectations about data source, privacy, and freshness.

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

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

The description is concise with no wasted words. It is front-loaded with purpose, then bullet-like use cases, then technical details. Every sentence adds value, and the structure is easy to scan.

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

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

Given the tool's simplicity (one optional enum parameter, no nested objects, no output schema), the description is fully complete. It explains what is returned, caching, privacy, and use cases. No missing critical information for agent decision.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add new parameter semantics beyond the schema's description and enum, as the window parameter is fully described in the schema. The description's use cases imply the parameter's effect but do not provide additional technical details.

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

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

The description clearly states the tool returns top tools, packs, and call volume over recent windows, with a specific verb 'returns' and resource 'top tools, packs, and call volume'. It distinguishes from siblings like 'ask_pipeworx' by focusing on aggregate trending data rather than direct Q&A.

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 three use cases (discovering hot sources, confirming canonical choice, seeing alignment), giving clear context on when to use. It does not explicitly state when not to use or name alternatives, but the use cases imply differentiation from sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=true. Description adds that it returns journey options (legs, durations, modes) and that ambiguous inputs lead to disambiguation responses instead. This extra context is valuable beyond annotations.

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

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

Two sentences: first states core purpose and parameter formats, second describes return behavior and error handling. Every sentence earns its place, front-loaded with action, no wasted words.

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

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

Given no output schema, description adequately explains return types (journey options with legs, durations, modes) and handles the special case of ambiguous locations. Parameters are fully covered by schema, and description adds behavioral nuances. Context signals indicate schema coverage 100%, so description complements well.

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

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

Schema already describes both parameters with 100% coverage. Description adds value by listing acceptable input formats (stop names, postcodes, 'lat,lon') and mentioning the disambiguation behavior, which helps the agent understand parameter edge cases.

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

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

Description clearly states the tool plans a journey across London transport, specifying that from/to can be stop names, postcodes, or 'lat,lon' coordinates. It distinguishes from sibling tools like 'arrivals' or 'stop_search' by focusing on journey planning rather than real-time arrivals or stop lookup.

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

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

Description explains when to use (planning a journey) and provides guidance on handling ambiguous locations: if ambiguous, API returns disambiguation options, so refine input or use naptanId/coords. It doesn't explicitly state when not to use, but sibling tools are diverse enough that this is sufficient.

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

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

The description goes well beyond annotations, explaining internal logic (monotonicity, partition checks, semantic anchor, fill check) and edge cases (placeholder filters, thin legs). No contradiction with annotations exists; all indicate safe, read-only analysis.

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

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

The description is long but well-structured with sections and front-loaded purpose. Every sentence is informative, though some details could be streamlined. It's efficient given the complexity.

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

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

Despite no output schema, the description fully explains the response structure and key outputs (opportunities[], partition_check, fill_check). All necessary context for correct invocation is present, including cross-event caveats and redirects.

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, and the tool description adds significant value by explaining modes, giving examples (slugs, topics), and noting that full URLs are accepted. The meaning of each parameter is fully elaborated.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between modes (trending_scan, event, topic) and provides specific examples, making the purpose unambiguous.

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

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

The description explicitly states when to use each argument: no args for trending_scan, event for a specific market, topic for cross-event scan. It also explains the differences between modes and redirects to polymarket_fill_risk for custom sizing, offering clear usage guidance.

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

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

The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent with the description. The description adds significant behavioral context beyond annotations, including caching details ('Cached 1h at the KV level keyed on all knobs'), response structure ('by_segment', '_diagnostics'), and tradeable-edge filters. No contradiction exists.

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

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

The description is detailed and structured, front-loading purpose and key details. While verbose, every sentence provides necessary information (model families, tradeable-edge knobs, diagnostics). It could be slightly more concise, but it balances completeness with clear organization.

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 9 parameters, no output schema, and rich annotations, the description is fully complete. It covers response structure, caching, diagnostics for empty segments, tradeable-edge filters, and model families. An agent can understand exactly what the tool does and how to invoke it correctly without additional information.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter purpose and usage beyond the schema, for example 'slippage_pp' includes market context ('Polymarket has zero trading fees...') and practical advice ('Bump for very thin partitions'). Parameters like 'min_partition_leg_kelly' are explained in relation to other parameters. Thus exceeds 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 tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs (scan/return) and identifies the resource (Polymarket markets). The title 'Polymarket Edges' is descriptive, and the description distinguishes it from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement.

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 use case: 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' This provides clear context for when to use the tool. While it doesn't explicitly list exclusions or alternatives, the purpose is well-defined and distinct from 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?

Descriptions adds significant behavioral context beyond annotations: data source (daily snapshots), gaps on cache-miss, 60-day TTL, decay computation details (daily closes not intraday). No contradiction with readOnlyHint, openWorldHint, idempotentHint, or 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?

Description is well-structured with a clear opening, detailed response breakdown, and limits section. It is fairly long but every sentence adds value; minor room for trimming but overall effective.

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

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

No output schema provided, but the description fully compensates by detailing response structure (tracked[], expired[], snapshot_dates[]) and explaining each field. Limits and caveats are also covered, making the tool's behavior completely understandable.

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

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

Both parameters (days, window) have full schema descriptions. The tool description adds value by providing defaults, allowed ranges, and semantic labels (lookback, snapshot family) that clarify usage beyond schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on historical persistence.

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 context for usage by contrasting fresh vs old edges, but lacks explicit when-to-use and when-not-to-use guidance. Sibling tools are implied but not directly compared.

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

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

Annotations declare readonly and idempotent, which description reinforces. Description adds substantial behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), includes a verdict (clean|degraded|cannot_fill), and warns about thin legs and forced directional risk. No contradiction with annotations.

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

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

Description is moderately long but well-structured with clear sections for single-market and basket modes. It uses bold for key terms and bullet-like lists. Could be slightly more concise, but given the complexity of the tool, the length is justified.

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

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

Despite no output schema, description thoroughly documents return fields for both modes, including edge cases like thin_legs and forced_directional_risk. It covers all four parameters, default behaviors, and cross-references sibling tools. The tool's complexity is fully addressed.

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

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

Schema coverage is 100% with descriptions, but description adds significant value beyond that: default values for size_usd and side, mode-dependent interpretation of size_usd (max spend on buys vs target proceeds on sells vs settlement notional in basket), and default side logic for basket. This enriches the schema considerably.

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 performs a realizable-vs-theoretical edge check against live order book depth, with explicit modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it. The verb 'check' and resource 'Polymarket Fill Risk' are specific.

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

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

Description explicitly instructs 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why partial basket fills convert arb into unhedged directional position, and notes required parameters for each mode. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are complemented by extensive description: spread calculation formula, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanation of spread meaning. It discloses that temporal misalignment makes spreads meaningless, which goes beyond what annotations provide.

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

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

The description is well-structured with a clear first sentence, bold headings for modes, and a separate paragraph for safety fields. Every sentence adds value, but it is somewhat lengthy. Could be slightly tightened without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description fully explains the response (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and provides warnings about real-world rarity of tradeable spreads. No apparent 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%, so the schema already documents parameters. The description adds value by explaining the 'topic' parameter with the list of shortcuts and that it auto-fetches matching events, and that explicit parameters override the topic-mapped side. It clarifies how parameters interact.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' with specific verb (get spread) and resource (cross-venue spread). It distinguishes itself from siblings by being the only tool that computes spreads across these two venues.

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

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

Two modes are explicitly explained: 'topic' for pre-mapped shortcuts and explicit parameters for custom pairings. The description warns that most pre-mapped topics yield compatibility warnings, guiding agents to not assume tradeability. However, it stops short of explicitly stating when not to use this tool (e.g., if only one venue is of interest).

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 and destructiveHint=false. The description adds scoping information (identifier-based) beyond annotations, and does not contradict 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 with three sentences, front-loading the core action. Every sentence adds value with 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?

For a simple retrieval tool with one parameter, the description covers purpose, scoping, and pairing. However, it does not describe return values, which could be inferred but is not explicit.

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

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

Schema coverage is 100% with clear parameter description. The description repeats the schema's hint about omitting the key to list all keys, adding no new meaning beyond what the schema provides.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, distinguishing it from sibling tools like remember and forget. It specifies the verb and resource accurately.

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

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

The description explains when to use the tool (e.g., to look up previously stored context) and mentions pairing with remember and forget, but does not explicitly state when not to use it or compare with other sibling tools 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 indicate read-only, idempotent, non-destructive. The description adds value by explaining mark_read state change and polling suitability, 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?

Three sentences, each earning its place: purpose, returned fields, usage hints. Front-loaded and no wasted words.

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

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

Lacks output schema but describes return fields. Covers parameters well and mentions alternative URL. Missing default limit and mark_read default, but schema provides them.

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

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

Schema coverage is 100%, so baseline is 3. The description adds behavioral context for mark_read, enhancing understanding beyond schema descriptions.

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

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

The description clearly states the tool pulls fired events from the subscription feed and lists key fields returned. It is specific but does not explicitly differentiate 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 explains filtering by type and since, mark_read behavior, and provides an alternative access URL. It offers clear context but lacks explicit when-not-to-use guidance.

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

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

The description discloses behaviors beyond annotations, including parallel fan-out to multiple sources, fallback mechanism (GDELT to GNews on rate limits/5xx), USPTO soft-fail due to API sunset, accepted values for 'since' (ISO date and relative shorthand), and return format (structured changes[], total_changes count, citation URIs). Annotations already indicate safe, idempotent, non-destructive operation, and the description adds rich context.

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

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

The description is relatively long but well-structured: starts with example queries, defines core purpose, details sources with behaviors, explains parameters, describes output, and provides alternative guidance. Every sentence adds value with minimal redundancy. Could be slightly tightened, but effective.

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

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

Despite no output schema and only 3 parameters, the description thoroughly covers inputs, source behaviors (including fallback and sunset), and output structure (grouped changes, total count, URIs). It also provides an alternative tool reference. Edge cases like empty results are implicit but not explicit. Overall, it compensates well for the missing output schema.

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

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

With 100% schema description coverage, baseline is 3. The description adds meaningful usage hints beyond schema: explains 'since' relative shorthand examples ('7d', '30d', '3m', '1y'), recommends '30d' or '1m' for monitoring, and clarifies 'value' can be ticker or CIK. This adds moderate value.

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

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

The description clearly states the tool's purpose with example queries ('What's new with X', 'latest on Y', etc.) and a concise definition: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists the aggregated sources (SEC EDGAR, GDELT/GNews, USPTO) and explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use that instead.

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

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

The description gives explicit guidance on when to use this tool vs. the alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also implies usage context through example queries and provides parameter guidance (e.g., 'Use "30d" or "1m" for typical monitoring').

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

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

Adds context beyond annotations: scoping, persistence duration for authenticated vs anonymous. Could mention overwrite behavior but not required. No contradiction with idempotentHint=true.

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

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

Five efficient sentences, front-loaded with action and purpose. Each sentence adds distinct value without redundancy.

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

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

For a simple 2-param tool with no output schema, description covers purpose, usage, behavioral details, and sibling relationships. Fully 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?

Schemas cover parameters with descriptions; tool description adds real-world examples (e.g., 'subject_property', 'target_ticker') and value types, enhancing semantic understanding.

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

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

Description clearly states the tool saves data for reuse later, defines it as key-value storage scoped by identifier, and distinguishes from siblings recall and forget by explicitly mentioning pairing.

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 (discover something worth carrying forward) and provides persistence context. Lacks explicit 'when not to use' but strong guidance overall.

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 value beyond the annotations by explaining internal behavior: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' No contradictions with annotations (readOnlyHint, openWorldHint, etc.).

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

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

The description is well-structured, starting with example queries and then detailing supported types. It is somewhat long but every sentence provides useful information. Could be slightly trimmed but overall effective.

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

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

Despite no output schema, the description fully documents return values for each entity type, including citation URIs. It covers all necessary information for an agent to use the tool correctly, including the cascading lookup behavior.

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

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

Schema coverage is 100%, but the description adds significant detail: for 'type' it lists the enum values and elaborates on what each returns (e.g., ticker + CIK for company, RxCUI for drug). For 'value' it gives examples and clarifies input formats (ticker, CIK, name). This exceeds 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 starts with concrete user queries like "What's the ticker for..." and explicitly states it resolves names to canonical identifiers. It clearly lists supported types (company, drug) and what each returns, distinguishing it from sibling tools by noting 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 usage guidance. It does not explicitly mention when not to use it or compare to other sibling tools like compare_entities, but the context is adequate for the agent.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks, and returns score, confidence, signal density. No contradiction.

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

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

Two succinct sentences, front-loaded with function, then usage and output. Every sentence adds value.

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

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

No output schema, but describes return format (ranked list with score, confidence, signal density). Covers function, usage, parameters comprehensively.

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

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

Schema coverage is 100%. Description enriches meaning: entities first is subject, models and _apiKey relationship, context as shared context. Adds value beyond schema.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check, ranks by score, and identifies most/least recognized. It distinguishes from siblings like ai_visibility_check and compare_entities.

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

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

Provides explicit use case: competitive AI-marketing audits. Implicitly suggests when to use instead of ai_visibility_check, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: external service calls, potential 5-30s delay for first measurement, and graceful degradation with sources_failed listing. 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 a single paragraph that covers major points without redundancy. It is front-loaded with the core purpose, though it could benefit from slightly more structured formatting for 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 tool's complexity (composite check, multiple data sources), the description provides sufficient detail about return values and edge cases. However, the absence of an output schema is partially compensated by the detailed summary of returned fields.

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

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

Schema coverage is 100% with clear parameter descriptions. The description reinforces the meaning but does not add new semantic constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages across deps.dev and bundlephobia. It distinguishes itself from siblings by explicitly noting the NPM-only scope and directing other ecosystems to deps.dev:version.

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

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

Explicitly states when to use: when an agent asks about npm package safety, popularity, or size. Also clarifies that other ecosystems are handled by a different tool, providing clear guidance on alternatives.

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

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

Goes far beyond annotations by detailing the embedding model (BGE-base-en), similarity measure (cosine), windowing (500-char overlapping), output format (character offsets + scores), and truncation behavior (200K char cap with flagging). 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?

A single, well-structured paragraph that front-loads the core action, then adds usage guidance, pairing information, and technical details. Every sentence provides value without redundancy.

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

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

Fully explains what the tool returns (passages with offsets and scores), its technical underpinnings, and its limitations (200K char cap, truncation). With no output schema, this description is complete enough for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for query and mentions the limit range, but these are already in the schema descriptions. Minimal additional semantic enrichment 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 uses a specific verb ('search inside') and resource ('fetched record'), provides concrete examples (SEC 10-K, article), and distinguishes itself from siblings like ask_pipeworx_grounded by explaining its role as an internal search on already-fetched text.

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

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

Explicitly states when to use ('when the record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded. Does not provide counterexamples or explicit 'when not to use', but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. The description adds value by listing return fields (modes, zone, lat/lon) and the connection to arrivals. However, it does not disclose any additional behavioral traits like rate limits or data freshness.

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?

A single, well-structured sentence. No filler words. Every part adds value: action, input, output fields, and cross-reference to sibling. It 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 2-parameter search tool with 100% schema coverage and no output schema, the description adequately explains what is returned and how it connects to another tool. It is complete for the complexity level.

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

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

Schema covers 100% of parameters with descriptions. The description adds minimal context beyond the schema (e.g., that the result id is for arrivals). Baseline 3 is appropriate since schema already carries the parameter details.

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

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

Description clearly states the action (search) and resource (stops/stations). It mentions key output fields (naptanId, modes, zone, lat/lon) and even connects to the arrivals tool, but does not explicitly differentiate from sibling tools like 'arrivals' or 'resolve_entity'.

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 a use case (using the id for arrivals) but provides no conditions for when to use or avoid this tool. Given many sibling tools, explicit guidance on when to choose this over others (e.g., 'arrivals' or 'resolve_entity') is missing.

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

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

Discloses mutation (create), auth requirement, delivery behavior, rate limit (10/day for SMS), and webhook auto-disable after 10 failures. No contradiction with annotations; adds value beyond them.

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

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

Well-structured: purpose, requirements, types, delivery. Dense but each sentence adds value. Could be slightly tighter, but appropriate 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?

Covers auth, types, delivery options, constraints, return value, and failure recovery. No output schema, but description sufficiently explains what is returned and behaviors.

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

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

Schema covers 100% of parameters with descriptions, but the description adds concrete examples for each type and clarifies usage (e.g., required fields per type). Adds meaning beyond schema.

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

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

Clearly states verb 'Create' and resource 'proactive monitoring subscription' with live-data event stream. Returns subscription ID, distinguishing from siblings like unsubscribe or list_subscriptions.

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

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

Explicitly requires Pipeworx OAuth account, lists supported types and delivery channels with examples and constraints (phone verification, cap). Does not explicitly exclude scenarios, but context is clear given sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds context that it returns category-bucketed example questions with exact tool+argument shape, and explains behavior with no args vs. topic. 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 dense but efficient, front-loading the purpose and example queries. Every sentence adds value, though it could be slightly more concise. 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?

With no output schema, the description adequately explains what the tool returns (category-bucketed example questions with tool+argument shape). It covers the optional parameter and usage context, making the description complete for a simple tool with strong annotations.

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

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

Schema coverage is 100% (one parameter with description). The description adds more detail about valid topics and the effect of omitting vs. passing topic, providing meaningful guidance 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: it returns example questions for users to ask, organized by category, and serves as the onboarding entry point. It distinguishes itself from siblings by being the first tool to use when learning about Pipeworx.

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

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

The description explicitly says to use this tool FIRST when you don't know what Pipeworx can do, or to learn how to call meta-tools. It also covers the optional topic parameter for focus. While it doesn't explicitly list when not to use it, the guidance is clear and sufficient.

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

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

Annotations already indicate idempotent and not destructive. Description adds that row is deactivated not deleted, and historical events remain. Adds value beyond annotations.

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

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

Two sentences, front-loaded with action, no unnecessary words. Efficient and clear.

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

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

No output schema, but description covers purpose, ownership, effect, and relation to recent_alerts. Could mention idempotency but not 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 100% with parameter description. Description adds that id is returned by subscribe, linking to sibling tool. Slightly above 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?

Clearly states the verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'. Mentions ownership enforcement, adding specificity.

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

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

Provides clear context: cancel your own subscription by id. Implicitly excludes others' subscriptions. Mentions historical events stay via recent_alerts, but no explicit when-not-to-use.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the return format: verdicts, structured form, actual value with citation, and percent delta. It also explains the scope (company-financial claims via SEC EDGAR + XBRL) and efficiency benefit. 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 efficiently written with front-loaded examples and clear structure. It could be slightly tighter, but every sentence serves a purpose: clarifying usage, scope, and return values.

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

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

For a simple tool with one parameter, no output schema, and rich annotations, the description is fully complete. It explains the domain, return format, and how it replaces multiple calls, leaving no ambiguity.

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

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

The input schema already fully describes the 'claim' parameter with 100% coverage. The description adds value by providing natural-language examples (e.g., 'Apple's FY2024 revenue was $400 billion'), reinforcing the type of input expected.

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 validates natural-language claims against authoritative sources, with specific examples like 'fact check' and 'verify the claim that...'. It distinguishes from siblings by being a specialized claim verification tool, not a general search or lookup tool.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also mentions it replaces 4-6 sequential calls. However, it doesn't explicitly state when not to use it, but the context is clear and no sibling overlaps.

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