Tfl

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

Annotations already declare readOnlyHint=true, openWorldHint=true, etc., and the description adds value by explaining return structure (per-model fields and combined view), pricing implications for Anthropic, and the default model. 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 of 4 sentences, front-loaded with the main action. It covers all necessary aspects without verbosity, though bullet points could improve scannability.

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

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

Given no output schema, the description adequately describes the return fields (score, confidence, signals, raw_response) and scoring range. It covers key parameter behaviors but omits error handling or API call limits.

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 meaningful descriptions. The description adds further context: entity examples, default model for models, the cost implication for _apiKey, and disambiguation role for context. This enhances understanding beyond the schema.

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

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

The description clearly states the action (Probe LLMs), the resource (LLMs), and the specific output (visibility score 0-100 per model). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on a scored probe rather than 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 lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) but does not explicitly say when NOT to use it or provide alternatives among siblings. It implies usage context but no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. Description adds that results are sorted by timeToStation, but does not describe response format or potential limitations. Acceptable given annotation coverage.

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

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

Two sentences with no fluff. Front-loaded with key information: what it does, how to use it, and how results are sorted.

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, good annotations, and no output schema, the description is largely complete. It covers purpose, input, and ordering. Could mention that it returns a list of arrivals, but that is implicit.

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 the sole parameter with a clear description. The description adds an example ('940GZZLUOXC') and context (obtained from stop_search), enriching the bare 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 it provides real-time predicted arrivals at a stop, specifies the input source (naptanId from stop_search), and distinguishes from siblings like stop_search (which obtains stop IDs) and plan_journey (which plans routes).

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 instructs to pass the naptanId from stop_search, implying the prerequisite step. While no explicit when-not-to-use or alternatives are given, the context is clear enough for a simple tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds rich context: routing to 3,272 tools, filling arguments, returning structured answers with stable citation URIs. This goes beyond annotations, though it doesn't detail potential limits or error 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?

The description is well-structured with a bold preference statement, a list of covered domains, usage cues, and examples. While it is relatively long, every sentence adds value and contributes to clarity. Minor redundancy (e.g., multiple aliases mentioned in schema and repeated in description) could be trimmed.

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

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

Given the tool's complexity (routing among thousands of sources), the description provides comprehensive context: what it does, when to use it, what kind of input is expected, and what the output looks like (structured answer with citation URIs). No output schema, but the description compensates 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 coverage is 100% with six alias parameters all mapping to 'question'. The description does not add new parameter semantics beyond the schema, but it provides concrete examples that clarify the expected input format and scope, which is helpful for the agent.

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

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

The description clearly states the tool's purpose: answering factual queries about real-world entities and data using authoritative structured sources. It uses specific verbs like 'answers', 'routes', and explicitly distinguishes from web search, 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 says 'PREFER OVER WEB SEARCH' and provides detailed when-to-use guidance with numerous examples of query types and domains. It also implies when not to use (e.g., for non-factual questions) by listing what it's good for.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral details: resolver resolution, classifier logic, fan-out examples, safety short-circuiting, closed market handling, wide spread warnings. 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 thorough but verbose and dense, lacking structural organization. While every sentence adds value, the length may overwhelm; a more concise or bulleted format would improve usability.

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 (classifiers, fan-outs, response shapes, error states), the description covers resolver contract, parent_event, news fields, safety mechanisms, and statuses. No output schema exists, so the description fully compensates.

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

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

Schema covers 100% of parameters with descriptions. The description adds significant context: depth enum meanings (quick vs thorough), include_raw behavior (summarized vs raw), and market input format elaboration (slug, URL, question).

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, specifies inputs (slug, URL, question), and lists use cases. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges via explicit usage guidance.

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 ('should I bet on X', 'what does the data say about Y') and examples. It does not directly state when not to use, but the scope is well-defined, and siblings implicitly serve as 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 true, and destructiveHint false. The description adds that data is live availability and includes 'additionalProperties' for bikes, empty docks, total docks, 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?

The description is two sentences, front-loaded with the main purpose. Every word adds value; no extraneous information.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers purpose, filtering behavior, and return structure (additionalProperties). No gaps remain.

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

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

Schema coverage is 100% with one parameter 'search' documented. The description adds that search is optional, filters by name/area, and gives an example ('Clerkenwell'), providing meaning beyond the schema's description.

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

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

The description clearly states the tool retrieves Santander Cycle docking stations with live availability, specifying the resource (docking stations) and verb (list/filter). It distinguishes from sibling tools, none of which appear related to bike data.

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

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

The description explicitly states when to use the optional search parameter ('filter by name/area') and when to omit it ('list all docking stations'). While it doesn't mention alternatives, the sibling list shows no similar tool, so the 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 declare readOnly, openWorld, idempotent, non-destructive; description adds value by explaining data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), the fix for off-calendar fiscal years, and that results are sorted by primary metric. No contradiction with annotations.

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

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

Single paragraph, front-loaded with purpose and usage. Includes technical detail about the fix but it is relevant. Could be slightly more concise, but overall efficient.

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

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

Given complexity (two types), 100% schema coverage, and annotations, description covers input, output format (paired data + citation URIs), sorting, and edge case handling (off-calendar fiscal years). Missing explicit mention of error handling for missing entities, but adequate for most agents.

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. Description adds meaning beyond schema: explains that values are tickers/CIKs for companies and drug names for drugs, provides examples, and clarifies the entity type enum. This extra context raises it above 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?

Clearly states it compares 2-5 companies or drugs side by side, listing specific data points for each type. Distinguishes from sibling tools like entity_profile by focusing on side-by-side comparison.

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: for comparison and ranking queries like 'compare X and Y', 'X vs Y', 'which is bigger'. Mentions it replaces 8-15 sequential lookups. Does not specify when not to use or alternatives, but context is clear.

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

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

Annotations indicate idempotent, read-only, non-destructive behavior. Description adds that it returns top-N tools with full schemas and examples, ready to call directly, providing important 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?

Description is fairly long but well-structured with front-loaded purpose. Each sentence adds value (domain list, return format, usage guidance), though it could be slightly more concise.

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

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

Given the tool's purpose (tool discovery), the description provides complete context: when to use, what it returns (tools with schemas and examples), and how to use it. Annotations cover safety, and schema is complete.

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

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

Schema coverage is 100% with clear descriptions for each parameter. Description adds extra context like default limit (20) and max (50), and explains that 'query' accepts task, q, etc. as aliases, enhancing parameter understanding.

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

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

The description clearly states that discover_tools finds tools by describing the data or task, and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that perform specific functions.

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', providing clear context for when to use this discovery tool before others.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that output includes 'description and affected lines', which is useful but limited. No contradictions.

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

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

Single sentence with no superfluous words. Directly conveys the tool's function and output components in a clear, front-loaded manner.

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

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

For a simple retrieval tool with one optional parameter, the description is sufficient. It mentions output details (description, affected lines) but could optionally clarify response format when no disruptions exist. Overall well-matched to complexity.

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

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

Schema description coverage is 100% for the single parameter 'modes', including allowed values and default. The tool description merely references 'given transport modes' without adding extra meaning, so baseline score 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 provides 'current disruptions' for specified transport modes, including description and affected lines. It uses a specific verb-resource pair and distinguishes from siblings like 'line_status' (current status) and 'arrivals' (next arrivals).

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

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

The description implies usage (when disruptions are needed) but provides no explicit guidance on when not to use this tool or comparison to alternatives like 'line_status'. The context is clear but lacks proactive selection advice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: specifics on return data (e.g., fundamentals sorted by period_end DESC, a note on a data fix for FY2025 numbers, patents API sunset causing soft-fail, and GDELT→GNews fallback). No contradictions with annotations.

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

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

The description is dense with information but well-structured, starting with main purpose then enumerating return fields and caveats. While every sentence adds value, it is somewhat lengthy; a slightly more concise presentation could be achieved without losing essential 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?

Without an output schema, the description thoroughly covers what is returned: cik, company_name, recent_filings (with URIs), fundamentals (specific fields and ordering), patents (with sunset warning), news (with fallback), LEI. It also addresses error cases (unsupported name input) and future plans (person/place types).

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by specifying acceptable values (ticker or zero-padded CIK) and clarifying that names are not supported. It also explains the type parameter only supports 'company.'

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 'Get everything about a US public company in one call,' which is a specific verb+resource. It distinguishes from siblings by stating when to use this tool versus calling multiple other tools, and it explicitly contrasts with resolve_entity for name resolution.

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

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

It explicitly states when to use: 'when a user asks tell me about X, research Acme, brief me on Tesla, or you'd otherwise call 10+ pack tools.' It also provides a clear exclusion: 'Pass ticker AAPL or zero-padded CIK 0000320193 — names not supported (use resolve_entity first).'

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 destructive and idempotent behavior. Description adds context on why to delete, but no additional behavioral traits 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 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?

Adequate for a simple delete tool with one parameter and clear annotations. Could mention irreversibility or provide an example, but not necessary.

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 clear parameter description. Tool description adds no extra parameter info 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?

Clearly states it deletes a stored memory by key. Distinguishes from sibling tools 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 describes when to use (stale context, task done, clear sensitive data) and recommends pairing with remember and recall.

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 it's read-only, open-world, and idempotent. The description adds meaningful behavioral context: it fetches the page, extracts title/description/links, and emits standard llms.txt markdown. No contradictions with annotations.

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

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

The description is concise (3 sentences) and front-loaded with the main action and purpose. Every sentence adds value, with no redundant or filler content.

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

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

Given the tool's simplicity and the presence of annotations, the description covers purpose, output format, and use cases. It doesn't mention error handling or rate limits, but for a non-destructive, open-world tool this is acceptable. No output schema but description specifies output is a text blob.

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

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

Schema coverage is 100% with both parameters well-described in the schema. The description does not add extra parameter semantics beyond what's in the schema, which is acceptable but doesn't elevate the score.

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

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

The description clearly states the tool's function: generating a production-ready llms.txt file for any URL. It names the target use cases (indexing, drafting, auditing) and distinguishes from sibling tools like scan_competitor_ai_presence by focusing on llms.txt generation specifically.

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 concrete usage scenarios (client indexing, own project, auditing competitor). While it doesn't explicitly state when not to use it or mention alternatives, the context is clear and sufficient for an agent to decide.

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

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

Annotations already indicate the tool is read-only and idempotent. The description adds the return format (lineStatuses, statusSeverityDescription) but no further behavioral traits like error handling or data freshness. This adds some value but does not go beyond what annotations suggest.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no extraneous details. Every sentence contributes essential information, making it highly efficient.

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

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

Given the absence of an output schema, the description adequately explains the return shape. It covers the core functionality for a status-check tool, but could be slightly more complete by mentioning that modes and lineId are mutually exclusive or that multiple lines may be returned.

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

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

Both parameters are already well-documented in the schema with descriptions covering their usage and precedence. The description mostly restates this with examples, adding marginal value. With 100% schema coverage, the baseline is 3.

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

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

The description clearly states that the tool returns the current service status for London transport lines, specifying two input methods (modes or lineId) and the output fields (lineStatuses, statusSeverityDescription). This is a specific verb+resource combination that distinguishes 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?

The description explains the two ways to query (modes vs lineId) but does not provide explicit guidance on when to use each or when to prefer this tool over siblings. It implies that lineId is for a specific line and modes for multiple modes, but this is not elaborated with context or alternatives.

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

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

The description discloses that the tool is free, doesn't count against tool-call quota, and is rate-limited to 5 per identifier per day. It also mentions that team reads digests daily and feedback affects roadmap. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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 (4 sentences) and well-structured. It fronts the action ('Tell the Pipeworx team...') and then provides usage details and constraints. No wasted words.

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

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

Despite no output schema, the description covers everything needed: purpose, input semantics, limitations, and expected impact. It is complete for a feedback submission tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: it explains the type enum values in detail, mentions message length limit (2000 chars), and clarifies that context is optional. It adds value beyond the schema.

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

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

The description clearly states the tool is for sending feedback (bugs, feature gaps, praise) to the Pipeworx team. It specifies the exact types of feedback and distinguishes itself from sibling tools by being a direct communication channel.

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

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

The description explicitly explains when to use the tool (for bugs, features, data gaps, praise) and what not to do (don't paste end-user prompts). It provides clear guidance on how to format feedback and understands the tool's role relative to others.

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

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

Beyond annotations (readOnly, idempotent), description adds caching behavior (5min-1h), data source (CF analytics-engine), and PII safety. 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?

Two paragraphs, front-loaded with main action, bullet points for use cases. Every sentence adds value. No fluff.

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

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

Describes return fields (top tools, packs, count) and caching. With no output schema, explanation of what's returned is sufficient for a simple tool. Could mention limits but not essential.

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 parameter descriptions, so baseline is 3. Description adds nuance about window length (short vs. steady-state) but does not significantly exceed schema 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?

Description clearly states it returns top tools, packs, and call volume over a window. Lists specific use cases. Distinguishes itself from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on trending/aggregated data.

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

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

Explicitly states three use cases: discovering hot data sources, confirming canonical tools, and checking alignment. Does not mention when not to use it or alternative tools, but the guidance is clear enough.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by disclosing the disambiguation edge case, which is beyond annotation coverage.

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 convey purpose, inputs, outputs, and a critical edge case. Every sentence is informative with no redundancy.

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

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

The description covers the tool's core function, input variants, response format, and an edge case. Without an output schema, the summary of return content is helpful. Minor gap: could mention if additional parameters like time or date are supported.

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 covers both parameters at 100%. The description repeats these formats and adds the ambiguous-response caveat, providing moderate extra value but not significantly deepening parameter understanding.

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

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

The description clearly states it plans a journey across London transport and specifies the output includes legs, durations, and modes. This effectively distinguishes it from sibling tools, which cover unrelated domains.

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

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

The description explains acceptable input formats and the disambiguation response, guiding the agent on how to refine input. It does not explicitly mention when not to use the tool, but the context is clear.

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

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

Annotations indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds transparency by detailing the internal logic (walking child markets, computing partition checks, filtering placeholders) and response structure, fully disclosing operational details.

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 well-structured with bold headers for modes, but it is somewhat lengthy. Every sentence adds necessary context, but conciseness could be slightly improved by trimming redundant phrases.

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

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

Given no output schema, the description thoroughly covers expected response fields (opportunities[], gap_pp, suggested_trade, etc.) and explains filters and logic. No gaps for an AI agent to interpret the tool's behavior and output.

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

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

Schema coverage is 100% with descriptions for both parameters, but the tool description adds significant value by explaining the two modes and how each parameter triggers different behavior, including examples and clarification of 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: finding arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from sibling tools like polymarket_edges by focusing on arbitrage logic rather than edge detection.

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

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

The description explains when to use each mode (event for single events, topic for cross-event searches) and notes that cross-event mode catches patterns single-event misses. However, it does not explicitly mention when not to use this tool or compare it to siblings like polymarket_kalshi_spread.

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 all key behaviors beyond annotations: caching at 1h, three response segments with detailed edge calculations, slippage handling, Kelly capping, and diagnostics for empty results. It fully describes the response structure and tradeable-edge filters, with no contradictions to annotations.

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

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

The description is lengthy but well-structured with segments and clear explanations. It front-loads the core purpose and progressively details the components. While it could be trimmed of some internal math, it remains readable and informative for an AI agent.

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, no output schema, and 9 parameters, the description covers all necessary aspects: response format, caching, edge calculations, filtering knobs, and diagnostics. It provides enough information for a complete understanding without external references.

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

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

With 100% schema description coverage, the description adds substantial context to each parameter, such as explaining why min_kelly does not apply to partitions, how slippage_pp reflects Polymarket's fees, and practical defaults. This goes far beyond the schema's descriptions.

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

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

The description clearly states it scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and explicitly names the three model families. It distinguishes from siblings like polymarket_arbitrage and polymarket_kalshi_spread by focusing on daily opportunity scanning with specific edge calculations.

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

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

The description provides explicit guidance on when to use (daily scanning for tradeable bets) and includes knobs to filter for realizable edges. It mentions what specific outputs are available (like diagnostics for empty segments) but does not explicitly exclude alternatives or compare with 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 read-only, idempotent, and non-destructive behavior. The description goes far beyond by detailing compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal alignment checks, and skipped cross-type/subtype counters, providing rich behavioral context.

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

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

The description is well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded purpose. However, it is verbose and includes some repetition (e.g., warning about pre-mapped topics), which could be trimmed for an AI agent.

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

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

With no output schema, the description fully explains the response structure, including leg-by-leg prices, matched spreads, and all safety fields. It covers edge cases (no matches, mismatched bet shapes, temporal misalignment) and sets realistic expectations about tradeability.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds value by explaining how parameters interact (overriding topic-mapped sides) and providing examples, enriching understanding beyond the schema alone.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit event IDs) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on matched outcomes and compatibility warnings.

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 each mode, provides a list of pre-mapped topics, and warns that most are not tradeable. It also describes safety fields that help determine if a spread is meaningful, but does not explicitly contrast with alternative 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 and idempotentHint=true, indicating safe read operations. The description adds value by explaining scoping ('to your identifier'), dual mode (key vs list all), and pairing with remember/forget. 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: main action, usage guidance, and contextual pairing. No redundant information; every sentence earns its place. Front-loaded with the primary action.

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

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

For a simple retrieval tool with no output schema, the description covers the core behavior, scoping, and pairing with sibling tools. However, it does not describe the return format or potential errors, which could be inferred but are not explicit. Satisfactory given its simplicity and good annotations.

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

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

The single parameter 'key' is described in the schema (100% coverage). The description adds crucial semantics: explaining the two modes (omit key to list all, provide key to retrieve specific value), which goes beyond the schema's description. This fully compensates for the schema coverage.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses specific verbs ('retrieve', 'list') and resource ('saved values'), and distinguishes from sibling tools like 'remember' and 'forget'.

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

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

The description provides clear context: 'use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget. However, it does not explicitly exclude when not to use it or mention alternatives beyond 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?

The description adds significant behavioral context beyond annotations: parallel fan-out to multiple sources, fallback from GDELT to GNews, soft-failure for USPTO, and date parsing format. No contradictions with annotations (readOnlyHint, 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 long but every sentence adds value. It is front-loaded with purpose and use cases. Slightly verbose in listing sources, but appropriate given 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 explains the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers date parsing, sources, error handling, and distinguishes from sibling. Highly complete.

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

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

Schema coverage is 100%, and the description adds value by explaining the 'since' format in detail (ISO date vs relative shorthand like '7d', '30d'), clarifying 'value' can be ticker or CIK, and constraining 'type' to 'company'. Examples are provided.

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: 'What's new with a company in the last N days/months?' It lists concrete use cases and data sources (SEC, GDELT/GNews, USPTO), and explicitly distinguishes itself from sibling 'entity_profile'.

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

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

The description provides explicit when-to-use ('what's happening with X', 'news on Apple this month') and when-not-to-use ('Use entity_profile instead when you want the static profile'). It also describes fallback behavior for rate-limited sources.

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=false, destructiveHint=false, and idempotentHint=true. The description adds critical details about key-value storage scoped by identifier, persistence differences (authenticated users get permanent memory, anonymous sessions retain for 24 hours), and pairing with recall/forget. 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?

Four well-organized sentences: purpose, usage guidance, technical detail (scoping/persistence), and pairing. Every sentence adds 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?

The description fully covers the tool's behavior, including persistence rules and pairing with siblings, which is complete for a simple key-value store with no 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% with clear descriptions for 'key' and 'value'. The description enriches parameter meaning by providing examples of what values can be stored (findings, addresses, preferences, notes) and suggests naming conventions for keys (e.g., 'subject_property', 'target_ticker').

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

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

The description clearly states 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference, research subject). It explicitly mentions sibling tools 'recall' and 'forget', distinguishing the tool's role as a memory storage action.

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

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

The description advises use when discovering something worth carrying forward, and mentions pairing with recall/forget. It lacks explicit 'when not to use' but provides sufficient context for appropriate 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 (readOnlyHint, idempotentHint, etc.) are already present, and the description adds valuable context: it cascades through several lookup endpoints internally, replacing 2-3 manual lookups. 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 concise and well-structured: opens with a clear verb+resource statement, followed by usage guidance, then supported types with specific details. Every sentence adds value.

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

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

Despite no output schema, the description explains the return format for both entity types, making it complete for an agent to understand what the tool returns and how to use it.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by detailing the return format for each type (e.g., for company: ticker + CIK + citation URI), which is beyond what the schema provides.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical identifiers. It specifies supported types (company, drug) and what each returns, distinguishing it from sibling tools that require IDs as input.

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 FIRST when you have a name but need an ID', which is clear guidance on when to use. Does not mention when not to use or alternatives, but the context is strong enough for an 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?

Adds behavioral context beyond annotations: probes each entity, ranks, surfaces most/least recognized, returns scored list. Annotations already declare safety, but description enriches understanding of process and output.

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

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

Concise, front-loaded with action, then behavior, then use case. Every sentence adds value; no redundancy.

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

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

Covers purpose, usage, output format, parameter constraints, and underlying mechanism. No output schema, but description sufficiently explains return structure. Complete for this complexity.

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

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

Schema coverage is 100%, but description adds value: explains 'entities' first entry is subject, rest competitors. Also clarifies 'models' default and 'context' use. More than baseline.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check. It distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic).

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 gives a use case ('competitive AI-marketing audits') and implies when to use (multiple entities vs single). Contextualizes against sibling 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?

Disclosed partial failures and latency (bundlephobia first measurement can take 5-30s) beyond annotations. No contradictions with 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?

Single dense paragraph that front-loads purpose and then details behavior. Concise but could benefit from minor structural improvements (e.g., bullet points). Still effectively communicates 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?

Despite no output schema, the description adequately explains return content (summary block, advisories, links, alternate versions) and covers ecosystem scope, failure modes, and defaults. Complete for intended usage.

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

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

Both parameters have schema descriptions covering 100%. The description adds minimal value beyond the schema (e.g., mentions scoped packages for 'package'), so baseline 3 is appropriate.

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

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

Clearly states the composite check for adding npm packages, specifies data sources (deps.dev, bundlephobia) and what it returns (summary, advisories, links, alternatives). Distinguishes from siblings by specifying NPM-only in v1.

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 (queries like 'is X safe/popular/small' or 'cost of lodash') and when not (other ecosystems should use deps.dev:version directly). Provides clear decision context.

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

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

Annotations already declare safe read-only behavior. The description adds value by detailing exact return fields, which is helpful beyond the annotations. No contradictions.

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

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

Single sentence, front-loaded with action, minimal and efficient. Every word contributes meaning.

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

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

For a simple 2-parameter search tool with rich annotations, the description covers purpose, return fields, and links to sibling tool. Complete without 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 provides 100% coverage with descriptions for both parameters. The description reiterates the return values but does not add new meaning to the parameters themselves.

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

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

Clearly states the tool searches for stops/stations by name, specifies return fields including naptanId, and explicitly mentions its use by the arrivals sibling tool, providing strong differentiation.

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

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

Gives context that naptanId from results is used by the arrivals tool, implying usage before arrivals. However, it does not explicitly state when not to use or compare to other sibling search 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 the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: it returns a verdict with specific categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), extracts structured form, provides actual value with a pipeworx:// citation, and computes percent delta. It also outlines the data source (SEC EDGAR + XBRL) and scope limitation, 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 concise at about 5 sentences. It is front-loaded with the core purpose, then immediately provides usage guidance, followed by specific constraints and output details. Every sentence adds value; there is no redundancy or unnecessary 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 has a single parameter and no output schema, the description covers the essential aspects: purpose, usage, domain specificity, output structure, and efficiency gains. It lacks explicit handling of error cases or claims outside the supported domain, but overall it is sufficiently complete for an agent to understand when and how to use this tool.

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

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

The schema covers the single parameter 'claim' with a description. The tool description supplements this with concrete examples and explains what constitutes a valid claim (e.g., 'Apple's FY2024 revenue was $400 billion'). Since schema coverage is 100%, the baseline is 3; the extra context provided by the description justifies a 4.

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

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

The description clearly states the tool's purpose: fact-checking, verifying, validating, or confirming/refuting natural-language factual claims. It uses specific verbs and specifies the resource (authoritative sources). It distinguishes itself from sibling tools by explicitly noting that it replaces 4–6 sequential calls, setting it apart from other research or entity-lookup tools.

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

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

The description provides clear usage triggers: 'Use when an agent needs to check whether something a user said is true' and gives example phrasings. It does not explicitly mention when not to use the tool or list alternative tools, but given the sibling list, most are unrelated. The scope limitation (v1 supports company-financial claims) implicitly guides when it is appropriate.

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