Data Centrevaldeloire

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral traits: it probes multiple LLMs, returns per-model and combined results, and notes that Anthropic calls require a BYO key and cost. This enhances transparency beyond annotations.

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

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

The description is concise (3 sentences), front-loads the main action, and avoids unnecessary words. Every sentence adds value, making it easy for an AI agent to parse quickly.

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 (4 parameters, no output schema), the description adequately covers the purpose, parameter usage, return format, and use cases. It lacks details on error handling but is sufficient for effective agent selection.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the interplay between 'models' and '_apiKey' (e.g., 'Default model is Workers AI... pass _apiKey to also probe Anthropic'), and clarifies the role of 'entity' and 'context'. This goes beyond what the schema alone 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: to probe LLMs about a given entity and score visibility. It uses a specific verb ('probe') and resource ('LLMs for entity visibility'), and the mention of scoring (0-100) distinguishes it from sibling tools like 'scan_competitor_ai_presence'.

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

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

The description provides clear context for when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains parameter usage (default model, optional Anthropic with key). However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already mark it readOnly, openWorld, and idempotent, and the description adds meaningful behavior beyond that: it routes to 5,798 tools across 1,517 sources, fills arguments automatically, returns structured answers with stable citation URIs, and handles live news routes. This gives an agent a strong mental model of what happens when the tool is invoked.

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

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

The description is long but densely useful, and it is front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. The examples and alternative-tool guidance earn their place, though the block could be tightened slightly by trimming some overlapping example queries.

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

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

Given this is a complex routing tool with no output schema, the description is highly complete: it explains when to use it, what it does internally, what the return format is, which sibling tools to fall back on, and what types of questions are appropriate. Nothing critical is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the aliases and the main question parameter are already documented. The description adds value by giving many example questions and listing the kinds of factual queries the tool accepts, which helps agents formulate the question parameter correctly even beyond the schema's examples.

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

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

The description names a precise verb and resource: it routes user questions to the right tool among thousands of verified sources and returns a structured answer with pipeworx:// citation URIs. It also clearly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart without opening the schema.

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 prefer this tool over web search, instructs 'START HERE for most questions', and gives concrete alternatives: use ask_pipeworx_grounded for a grounded single answer and deep_research for broad multi-part questions. It also provides trigger phrases and examples that make the decision boundary easy to apply.

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 that already declare read-only, idempotent, and non-destructive hints, the description reveals dynamic state: candidate routing improvements are enabled live whenever under test, no candidate is currently active, and it matches ask_pipeworx exactly right now. This is valuable context the annotations cannot convey.

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

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

The description is three dense sentences with no wasted words. It front-loads the core identity, then adds current state and usage direction, and each sentence earns its place.

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

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

For a beta sibling tool, the description explains current candidate status, fallback behavior, and equivalence to the stable router in scope, arguments, and response shape. It relies on the sibling ask_pipeworx definition for full detail, which is reasonable but means an agent unfamiliar with that sibling would need additional context.

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

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

Schema description coverage is 100%, with all six parameters and aliases documented. The description adds no parameter-level meaning beyond referencing 'same arguments' as ask_pipeworx, so it meets the baseline but does not exceed it.

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 states with a specific verb and resource: it is a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It clearly distinguishes itself from the stable sibling by naming it and explaining it is the experimental edge.

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 tells the agent to use it exactly like ask_pipeworx when the newest routing is desired, and explains results are compared against the stable router. It stops short of a direct 'when not to use' statement, such as preferring the stable router for production, so it is clear but not fully exclusive.

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 detailed behavior beyond annotations: exact success return shape, explicit refusal reasons, and the extra LLM call cost. It explains refusal conditions ('when the data doesn't directly answer') and the grounding constraint, none of which are available in 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 information-dense but every sentence earns its place: purpose, routing, result contract, refusal contract, use cases, and cost trade-off. The most distinguishing characteristic (grounded extraction) is front-loaded, followed by practical invocation guidance.

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

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

Despite lacking an output schema, the description fully specifies the return contract including fields and refusal reason enum. It also gives routing context (5,798 tools, 1517 sources), differentiates from the sibling, and covers cost and usage boundaries. No critical invocation information is missing.

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

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

Schema description coverage is 100%, and the schema already documents the question parameter with aliases. The description adds no additional parameter-level meaning, which is appropriate given the high coverage; baseline 3 is warranted.

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

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

The description identifies a distinct mode ('hallucination-resistant answer mode for high-stakes reads') with a specific behavior: extract answers using ONLY the tool result contents. It explicitly distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but grounded extraction, making the differentiation clear.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with examples. It also provides a when-not-to-use rule: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost.

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

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

The description goes well beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing safety protocols, resolution contracts, parent event extraction, news fallback mechanisms, and handling of closed markets, wide spreads, and cancellation rules. 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 comprehensive but verbose, spanning multiple paragraphs. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), but could be more concise to improve readability for agents. Score 3 because it is not concise but organized.

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

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

Given the tool's complexity (multiple fan-out patterns, resolution logic, safety features), the description covers all essential aspects: inputs, outputs (even without an output schema), edge cases like low-confidence matches, closed markets, wide spreads, and resolution rules. It is complete for an agent to use correctly.

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

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

Input schema has 100% parameter description coverage, so baseline is 3. The description adds value by elaborating on the 'market' parameter with examples and explanations of slug, URL, or question text. For 'depth' and 'include_raw', it reinforces schema descriptions but does not add new semantics. Thus a 4 is justified.

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, specifying the verb 'research' and the resource. It distinguishes from siblings like polymarket_edges by focusing on data gathering 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 gives explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Examples of fan-out for various bet types provide context. However, it does not explicitly state when not to use or mention alternatives, though siblings like polymarket_edges exist for edge-specific 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it pulls latest data, handles off-calendar fiscal years correctly, returns sorted results, and provides citation URIs. This adds behavioral context beyond the annotations without contradiction.

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

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

The description is relatively long but well-structured with front-loaded trigger phrases. Every sentence adds value, though some redundancy could be trimmed. Overall efficient for the information conveyed.

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 2 parameters, 100% schema coverage, and no output schema, the description thoroughly covers input details and explains output characteristics (sorted, paired data, citation URIs). It could mention return format or pagination, but for this tool it is sufficiently 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?

The input schema covers 100% of parameters with descriptions, but the description adds critical meaning: explains that type='company' pulls revenue, net income, cash, debt; type='drug' pulls adverse-event counts, FDA approvals, trial counts. It also clarifies values format (tickers/CIKs for company, names for drug) and the 2–5 count constraint.

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 does side-by-side comparison of 2–5 companies or drugs, using specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs). It uses specific verbs like 'compare' and 'rank', and distinguishes from siblings like entity_profile and query by emphasizing parallel retrieval.

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 instructs to prefer this tool over sequential single-pack lookups when comparing entities, and lists natural language triggers ('compare X and Y', 'which is bigger', etc.). It does not provide when-not-to-use but clearly states the replacement benefit (8–15 sequential lookups).

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, and destructiveHint=false, so the tool's safety profile is clear. The description adds that the tool returns specific metadata (fields, themes, record count) but does not disclose additional traits like error handling or performance. Given the rich annotations, the description's marginal value is limited.

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, well-structured sentence that front-loads the key action and resource. Every word adds value: 'Get metadata', specifics of metadata, and usage advice. There is no redundancy or 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?

Given the tool's simplicity (1 parameter, no output schema, rich annotations), the description adequately covers the return contents (fields/schema, themes, record count) and the prerequisite for using the dataset_id. It lacks details about error conditions or the exact output format, but these are minor omissions.

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

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

The schema already fully describes the only parameter (dataset_id) with 100% coverage, including its source ('Dataset id from search_datasets'). The tool description does not add any further semantic meaning beyond what the schema provides, earning the baseline score of 3.

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

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

The description clearly states the verb 'Get' and resource 'metadata for one Centre-Val de Loire Open Data dataset', specifying the content (fields/schema, themes, record count). It distinguishes itself from sibling tools like search_datasets by focusing on a single dataset's metadata.

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: 'call before query to learn the column names.' This implies when to use (before querying data) and hints at the prerequisite of having a dataset_id from search_datasets. However, it does not explicitly mention alternatives or when not to use the tool.

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

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

Annotations already mark this read-only and idempotent, and the description adds substantial non-obvious behavior: account requirements, parallel decomposition across 5,798 tools, gap reporting rather than invention, contradictions scanning, fetchable citation URIs, semantic excerpting, and expected latency. This goes well beyond what annotations convey.

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

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

Despite being long, the description is front-loaded with auth and fallback guidance, then follows a logical order: core function, best use, depth behavior, output format, and performance. Every clause carries operational information relevant to selecting and invoking the tool.

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

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

With no output schema present, the description carries the full burden of explaining return data, and it does: findings packet contents, gaps, contradictions, citation behavior, and latency. It is complete enough for an agent to know what it will receive and how long to wait.

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

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

The schema already covers both parameters at 100%, but the description adds usage-level parameter guidance: the question should be broad/multi-part and single lookups should be routed to ask_pipeworx. It also reinforces the depth-level differences, though the schema already includes the paid note for thorough.

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 names a specific action and resource: grounded multi-source research over 1,517 structured data sources in one call. It also distinguishes itself from open-web search and from ask_pipeworx, making its role among siblings clear.

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

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

It explicitly says to use ask_pipeworx when not signed in and for single lookups, while deep_research is best for broad/multi-part questions requiring decomposition and parallel research. This provides both positive and negative usage conditions.

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 and idempotent behavior. Description adds that results include full schemas with examples, eliminating need for second lookup. Does not mention rate limits or pagination, but these are less critical for a read-only discovery tool.

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

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

Description is 5 sentences, front-loaded with purpose and examples. 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?

Despite missing output schema, description fully covers return value (top-N tools with schemas and examples). Context signals and sibling tools further inform the agent about its role.

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

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

Schema covers all 6 parameters (100% coverage). Description adds context by listing valid query examples and stating that accepted aliases exist. Provides a clear picture of the natural language 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?

Description clearly states the tool finds tools by describing data or task. Lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes from siblings by recommending it as a first step when many tools are available.

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 (browse, search, look up, discover) and when to call first. Provides context that it outputs ready-to-call tools, implying its role as a discovery gateway.

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 read-only, idempotent, open-world, and non-destructive, and the description adds substantial context: parallel fan-out across named sources, sources_used/sources_failed semantics, the meaning of an empty section as a real 'no data' result, and resolved:false behavior with notes. These details go well beyond the structured annotations.

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

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

The description is dense and front-loaded with the core purpose and the preference rule, and every sentence carries useful information. However, it is a long single paragraph with seven redundant example phrasings and some repetition of schema details; bullet structure would improve scannability without losing content.

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

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

There is no output schema, so the description carries the full burden of explaining return values; it does so thoroughly by enumerating cik, company_name, resolved_from/resolved_to, recent_filings, fundamentals, sources_used/sources_failed, and the private-company notes path. An agent can anticipate both the invocation and the response shape without additional context.

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

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

Schema coverage is 100%, but the description clearly adds meaning beyond the schema: type accepts 'company' or 'ticker' interchangeably, value can be a ticker, zero-padded CIK, or company name, names resolve via SEC EDGAR, and the description explains resolved_from/resolved_to behavior. This is a strong enrichment of the raw schema.

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

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

The description opens with concrete user-phrase examples and then states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chaining single-pack SEC/XBRL/news lookups and from the broader sibling set by defining its holistic scope.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' which is direct when-to-use guidance versus an alternative. It also tells the agent what input shapes are accepted and what happens for private companies, so the agent can decide correctly before calling.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data and pairing with remember/recall, but does not disclose additional behavioral traits like irreversible deletion.

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 short sentences, front-loaded with purpose, no wasted words. Efficient and scannable.

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 required parameter and no output schema, the description fully covers what the tool does, when to use it, and how it relates to siblings. No gaps.

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

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

Schema coverage is 100% and the key parameter has a clear description. Description adds no further parameter-level details beyond what schema provides, meeting baseline expectation.

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

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

Description starts with 'Delete a previously stored memory by key', providing a specific verb and resource that clearly distinguishes from siblings like remember and recall.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with remember and recall, signaling 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, idempotentHint=true, and destructiveHint=false. The description adds valuable context: fetches the page, extracts title/description/links, and emits standard markdown format. 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 efficient at ~5 sentences, front-loading the core purpose and output format. The 'Useful for' section adds structure, though it could be slightly trimmed 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 no output schema, the description explains the output as a single text blob. It covers parameters, use cases, and process. Lacks details on error handling or edge cases, but sufficient for a simple read-only 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 descriptions for both parameters. The description adds meaning by specifying the max_links default (25) and maximum (50) alongside the purpose of limiting link entries.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate', the resource 'llms.txt file', and the outcome. It distinguishes itself from siblings like 'scan_competitor_ai_presence' by focusing on file generation 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 provides explicit use cases (client indexing, personal projects, competitor auditing) and implies when to use it, but does not explicitly state when not to use it or name alternative 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. Description adds return field details and caller scope, but does not significantly extend behavioral context beyond what annotations provide. No contradiction.

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

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

Two sentences with no waste; first sentence states purpose and return fields, second gives usage guidance. Efficient and front-loaded.

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

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

For a simple tool with one optional parameter, clear annotations, and no output schema, the description fully covers purpose, usage, and 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% and the parameter description is self-explanatory. Description does not add information beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource, and explicitly distinguishes from siblings like subscribe and unsubscribe by mentioning its use for review before adding or canceling.

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 use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This implies when-not-to-use and alternatives (subscribe, unsubscribe), but lacks explicit exclusions or more formal usage boundaries.

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?

Despite annotations being all false (which offer no safety profile), the description discloses critical behaviors: rate limit ('5 per identifier per day'), return format ('claim_token'), how to repoll later, and that it's free and doesn't count against quota. It also states the human process ('team reads digests daily and signal directly affects roadmap'). This richly exceeds annotation information.

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 serves a purpose. It opens with a clear one-line purpose, then layers usage scope, exclusions, return behavior, and operational details in a logical order. No redundancy; the density is justified by the tool's multiple modes (report, praise, claim token).

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 fully explains what happens when filing (returns claim_token, can be reused), the scope (only Pipeworx-served tools), and the feedback content expectations (describe in terms of Pipeworx tools/packs). It also covers rate limiting and quota implications. Nothing critical is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful usage guidance beyond the schema: 'don't paste the end-user's prompt,' and for claim_token, 'pass the pwfb_… token that filing returned, with no other arguments.' This supplements the schema effectively, though it doesn't add per-parameter syntax 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?

Purpose is explicit: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' The verb 'tell' and resource 'Pipeworx team' clearly define the action. It stands apart from sibling tools like ask_pipeworx or deep_research, as this is uniquely the feedback 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?

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and a clear when-not-to-use exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' It also names the alternative (file with that server) and gives a disambiguation test ('Pipeworx tool names are the ones this connection lists').

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 valuable context: caching duration (5min-1h), data source (CF analytics-engine), absence of PII, and self-aggregating nature. This 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 (three sentences plus bulleted uses), well-structured, and every sentence adds value. No redundancy or fluff.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, return content, time windows, use cases, and caching. It is fully complete given the tool's complexity and rich 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 the single parameter (window) with enum values and descriptions. The description adds interpretive context ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which 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 explicitly states 'Returns the top tools, top packs, and total call volume over a recent window' and lists three specific use cases, making the purpose very clear. It distinguishes itself from siblings like 'discover_tools' by focusing on popularity signals derived from other agents' usage.

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 use cases (discovering hot data sources, confirming canonical choices, assessing alignment) but does not explicitly mention when not to use the tool or compare with alternatives. However, the use cases are sufficiently specific to guide appropriate usage.

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

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

Annotations (readOnlyHint: true, openWorldHint: true, idempotentHint: true, destructiveHint: false) are consistent with the description. The description adds rich behavioral context: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check with CLOB depth, and response structure. 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 detailed but well-structured with clear sections and bullet points. It front-loads the purpose and uses plain language. While long, it earns its place due to the tool's complexity. Could be slightly tightened 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?

Given no output schema, the description thoroughly explains response content (opportunities array, partition_check fields, fill check details). It covers all modes, edge cases (placeholder filtering, low similarity skipped), and provides sufficient context for the 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% with both parameters described. The description adds significant value beyond the schema by explaining the meaning of event slugs, topic seeds, and how each mode works. It provides examples and clarifies parameters, justifying a score 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?

The description clearly defines the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific examples, effectively differentiating from sibling tools.

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for the strongest per-event partition_check', or 'topic for a themed cross-event scan'. It also includes conditions for not trading (e.g., 'do not trade it' when fill check fails), and mentions alternatives like polymarket_fill_risk.

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 provides extensive behavioral details beyond the annotations, including the three response segments, edge calculation (edge_pp_net after slippage), Kelly fractions with caps, liquidity/spread filters, diagnostic information for empty segments, and a 1-hour KV cache. There is no contradiction with annotations.

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

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

The description is well-structured with segments and bold terms, but it is quite verbose (approximately 400 words). While the detail is valuable, some technical explanations (e.g., the full breakdown of model families) could be more concise or moved to external docs, making the description more 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 complexity of the tool (9 parameters, no output schema), the description is remarkably complete. It explains all three segments, the response structure, knob effects, and even why Fed bets are excluded. It compensates well for the lack of an 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?

All 9 parameters are described in the input schema (100% coverage), and the description adds extra context for several parameters (e.g., slippage_pp explains Polymarket fees, max_spread_pp advises a setting, min_partition_leg_kelly clarifies its relation to partition arbs). This adds value beyond the schema.

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

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

The description clearly identifies the tool's action (scan/return) and resource (top Polymarket markets) with a specific purpose: finding opportunities where Pipeworx data disagrees with market price. This distinguishes it from sibling tools like polymarket_arbitrage, which likely have different focuses.

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 it is 'built for what should I bet on today' and mentions agents can discover opportunities without paging hundreds of markets, providing clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternatives, which would elevate the score.

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

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

Adds significant depth beyond annotations: explains snapshot mechanism, meaning of trend/decay values, distinction between tracked and expired opportunities, and limitations (60-day TTL). No contradiction 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?

Well-structured: front-loaded summary, then detailed response fields. Every sentence adds value. Could be slightly more concise with bullet points for response format, but no wasted text.

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

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

Thoroughly explains response fields (tracked, expired, snapshot_dates) and limitations. No output schema exists, so description compensates fully. Complete for agent to understand tool behavior and results.

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

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

Both parameters (days, window) are fully described in schema (100% coverage). Description adds extra context: defaults, clamps, and meaning of window in response. Adds value but schema already covers basics.

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 edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. Distinguishes from siblings like polymarket_edges by focusing on historical time-series rather than current edges.

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 strong context on when to use: to differentiate fresh vs aged edges. Implicitly suggests not to use for current edge data, but does not explicitly name alternatives. Could be improved by stating 'for current edges, use polymarket_edges'.

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, safe, idempotent behavior. The description adds valuable behavioral context: it describes the order-book walking process, the return fields (top_of_book, vwap_fill_price, slippage, etc.), and identifies risks like forced directional risk. This fully informs the agent of the tool's operation 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 verbose but well-structured, with clear sections for single-market and basket modes. It front-loads the core purpose. While some repetition exists (e.g., 'walk the ladder'), every sentence contributes to understanding. It could be slightly trimmed, but it remains highly informative.

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

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

Given the complexity of the tool (two modes, no output schema), the description is remarkably complete. It covers return fields, interpretation of results, edge-case risks, and the rationale for using this tool. Without an output schema, the description compensates thoroughly.

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?

Although the input schema has 100% description coverage, the tool description adds significant meaning: it explains the default behavior for 'side' in basket mode (auto), interprets 'size_usd' differently for single-market vs basket (max spend vs settlement notional), and mentions the clamp range. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by positioning itself as a pre-check. The two modes (single-market and basket) are detailed, making the purpose unmistakable.

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

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

The description provides explicit usage guidance: it requires one of `market` or `event` parameters, and recommends using this tool before acting on arbitrage signals or trades above ~$500. It also warns against partial basket fills converting an arb into an unhedged position, effectively telling the agent when to use and when not to use.

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

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

Annotations already mark this as read-only, open-world, idempotent, and non-destructive, so the bar is lowered. The description goes far beyond that, disclosing the matching algorithm, compatibility warning codes, gross-vs-net fee treatment, skipped-leg behavior, and the fact that returned pairs are not necessarily equivalent bets.

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 and dense, but the complexity justifies much of it, and it is front-loaded with purpose before details. Some safety caveats are repeated, and a tighter edit could remove redundancy without losing value, so it is not a perfect 5.

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

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

There is no output schema, so the description carries full responsibility for explaining return behavior. It names most key response fields, warning codes, skipped-leg categories, and the fee disclosure, giving an agent enough to interpret results correctly.

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

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

Schema coverage is 100%, but the description adds meaning by explaining the topic enum values, how explicit tickers override topic-mapped sides, and the interaction between modes. It also clarifies that both modes run the same matcher, which is essential information not present in the schema.

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

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

The description states a specific task: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes two invocation modes and explains what the tool produces, making its role distinct from obvious siblings like polymarket_arbitrage even without naming them.

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

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

The description gives clear context on when to use it: for paired Kalshi/Polymarket questions, with pre-mapped shortcuts or explicit tickers. It does not explicitly compare against sibling tools like polymarket_arbitrage, but it thoroughly explains mode selection and warns that pre-mapped topics are often not tradeable, which is strong practical 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the tool uses ODSQL and that the 'where' parameter overrides 'query', providing useful behavioral context without contradiction.

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

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

The description is a single, well-structured sentence that front-loads the purpose and efficiently lists operations. No unnecessary words.

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

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

The description covers main operations but omits pagination details, the free-text query parameter, and the specific data source restriction (Centre-Val de Loire). Adequate but not fully comprehensive given parameter count.

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. The tool description restates parameters and adds high-level context (e.g., 'aggregate (group_by/select)') but does not significantly deepen understanding beyond the schema.

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

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

The description clearly states the tool queries records from a specific dataset using ODSQL, listing key operations (filter, aggregate, sort, paginate). It distinguishes from siblings like search_datasets by focusing on data within a dataset.

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 for querying records within a dataset but does not explicitly specify when to use this tool over alternatives like search_datasets. No when-not-to-use or exclusion criteria are provided.

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 that the tool is scoped to an identifier (anonymous IP, BYO key hash, account ID), which is valuable context beyond 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?

Two sentences with no redundancy. Front-loaded with the core action, then usage context, then pairing info. Every sentence adds value.

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

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

Given the simple nature of the tool and rich annotations, the description is complete. It explains scoping, pairing with other tools, and does not require an 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 a clear description of the 'key' parameter. The description adds context about what keys represent (ticker, address, notes) and the behavior when omitted (list all).

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all keys if the key argument is omitted. It specifies the resource (saved memories) and action (retrieve/list), and distinguishes from siblings 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?

Explicitly says when to use (look up context stored earlier) and provides alternatives (pair with remember to save, forget to delete). Implies not to use for deriving info from scratch.

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 reveals that setting mark_read:true flags events as read, a side effect that changes state. This directly contradicts the annotation readOnlyHint=true, which implies no state modifications. The contradiction is a serious issue, as annotations and description must be consistent. Without this conflict, the description would provide good 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 three sentences and front-loads the core purpose. Every sentence adds value: what it does, what it returns, how to filter, the mark_read behavior, and an alternative access method. No unnecessary words or repetition.

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

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

Despite lacking an output schema, the description fully explains return values (source, citation_uri, raw payload) and covers all essential behaviors: filtering, pagination via limit, mark_read side effect, unread_only, and polling suitability. 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 all parameters described. The description adds minimal value beyond the schema, offering an example filter type ('sec_8k') and noting that 'since' expects an ISO timestamp. This reinforcement is helpful but not essential, so the score remains at 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?

The description clearly states 'Pull fired events from your subscription feed' and specifies the return fields (source, citation_uri, raw event payload). It uniquely identifies the tool's action (retrieving recent alerts) and distinguishes it from siblings like 'subscribe' and 'list_subscriptions' which handle subscription management rather than data retrieval.

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 contexts by stating 'Polls work fine' and provides an alternative endpoint for scripts/dashboards, suggesting when to use this tool vs. direct HTTP access. It also mentions filtering by type and since, but does not explicitly exclude use cases or compare to sibling tools, which would strengthen the 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral detail: fans out to multiple sources (SEC, GDELT, GNews fallback, USPTO), explains fallback logic (GDELT preferred, GNews on rate limit/5xx), notes USPTO soft-fail until May 2025, and describes return format (changes[] grouped by source, total_changes, pipeworx:// URIs). No contradiction with annotations.

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

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

The description is a dense paragraph but front-loaded with example queries for quick understanding. Every sentence adds value, though the length could be slightly reduced by better structuring (e.g., list of sources). Still 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?

The tool is complex (multi-source aggregation, fallback logic, no output schema). The description covers return format, source behavior, and fallbacks comprehensively, leaving no major gaps. It is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds value beyond the schema: explains `since` format with examples ('2026-04-01' or '7d', '30d', '3m', '1y'), suggests '30d' for typical monitoring, and clarifies that `type` only supports 'company' and `value` can be ticker or CIK. This enhances 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 starts with example queries, clearly states it provides a change feed for a company within a time window, and distinguishes itself from the sibling tool 'entity_profile' which provides static profiles. The verb+resource is specific and actionable.

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 when to use this tool ('What's new with X') and when not to ('Use entity_profile instead when you want the static profile'). Also provides context like typical monitoring using '30d' or '1m'.

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 context beyond annotations: scoped by identifier, authenticated vs anonymous memory duration, key-value pair storage. 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?

Three sentences, each adding value. Front-loaded with main purpose. Efficiently 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?

For a simple write tool with good schema and annotations, the description covers usage, persistence, and pairing with other tools. 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%, so description adds marginal value. It provides example key patterns but doesn't add 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 saves data for reuse across conversations/sessions, with specific examples (resolved ticker, target address). It differentiates from siblings recall and forget.

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

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

Explicitly states when to use (discover something worth carrying forward) and mentions alternatives (recall to retrieve, forget to delete). Also clarifies scoping and persistence details.

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 the annotations, detailing graceful degradation ('if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), ambiguous-match behavior ('asserts nothing and returns `figi_candidates`'), and explicit unresolved handling ('stated explicitly under `unresolved`'). It also discloses internal cascading lookups and source labeling, 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 long but dense and well-structured: it front-loads the core purpose and usage rule, then uses clear labels ('SUPPORTED TYPES', 'LEI/FIGI enrichment') to organize complex details. Every sentence delivers actionable information, and the length is justified by the tool's scope and edge cases.

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 present, the description carries the burden of explaining return behavior. It does so thoroughly: mentions `figi_candidates`, `unresolved`, source-labeled identifiers, fallback behavior, and the drug-type return fields (RxCUI, ingredient, brand). This is complete enough for an agent to call the tool correctly and interpret results.

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?

Although schema description coverage is 100%, the description adds critical parameter semantics beyond the schema, especially for `value`: 'Pass the ENTITY NAME ONLY — for a bond that is the ISSUER exactly as printed... never the question's full noun phrase.' It also elaborates on the `type` parameter by explaining what each type resolves to and which input formats are accepted (ticker, CIK, ISIN, name).

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

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

The description opens with a specific, unambiguous statement of purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It also enumerates supported types (company, drug) and gives example queries, making it immediately clear what this tool does and that it is the name-to-ID resolver among the sibling tools.

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

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

The description provides a strong when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also gives concrete trigger examples and warns about the correct way to pass bond issuer names. However, it does not explicitly name alternatives or state when-not-to-use scenarios, so the guidance is clear but not fully 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. No contradictions.

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

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

Two sentences plus an illustrative question. Purpose is front-loaded, no wasted words, every sentence adds value.

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

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

Given the annotation coverage and full schema descriptions, the description explains the output format and process, making it complete for the tool's complexity.

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

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

Schema description coverage is 100%. The description adds meaning by noting the first entity is treated as 'subject' for narrative, and clarifies the models array and context 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 it compares AI visibility across multiple entities, ranks them by score, and surfaces most/least recognized. It distinguishes itself from ai_visibility_check (single entity) 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 a clear use case: competitive AI-marketing audits, with an example question. Implicitly contrasts with single-entity probing, but no explicit when-not-to-use or alternative tool names.

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 goes beyond annotations by detailing partial failure behavior (bundlephobia timeout of 5-30s, sources_failed list), ecosystem limitation (NPM only in v1), and graceful degradation. This adds significant value beyond the readOnlyHint, openWorldHint, and idempotentHint 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 efficiently covers purpose, sources, output fields, limitations, and edge cases. Every sentence is valuable, and it is well front-loaded with the core composite check intent.

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

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

Despite no output schema, the description lists all returned fields (summary block, per-advisory details, links, alternative versions, sources_failed). It also covers timeout behavior and ecosystem scope, making it fully contextual for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that 'version' defaults to latest and scoped packages are accepted, but this is minimal additional guidance beyond the schema descriptions.

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

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

The description clearly states that this tool is a composite check for evaluating npm packages, aggregating license, advisory, and size data from deps.dev and bundlephobia. It distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on npm dependencies and providing a unified risk/size assessment.

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

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

Explicitly says when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides an alternative: for other ecosystems like PyPI, use 'deps.dev:version directly'. This gives clear usage context and exclusion criteria.

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

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

Annotations already declare safety (readOnlyHint, idempotentHint). The description adds what the tool returns (dataset_ids, titles, themes, record counts) and the regional scope, which is helpful beyond annotations.

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

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

The description is a single, well-structured sentence that front-loads the purpose and includes key details without unnecessary words.

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

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

Given the simple schema and no output schema, the description adequately covers the search scope, return values, and how results link to other tools, making it complete for basic usage.

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

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

Schema covers all 3 parameters with 100% description coverage. The description does not add new details about parameters, 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 the tool searches for datasets by keyword in a specific open data portal, listing example themes and return fields. It distinguishes from sibling tools like dataset_info by noting that dataset_ids can be passed to them.

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

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

The description implies usage for keyword-based discovery and references downstream tools for IDs, giving context. However, it does not explicitly state when to avoid this tool or directly compare with all siblings.

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 behavioral traits beyond annotations: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars), truncation behavior ('truncated and flagged'), and output details (character offsets and similarity scores). No contradictions with annotations.

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

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

The description is extremely concise: three sentences that front-load the core purpose, then cover usage guidelines and technical details. Every sentence contributes meaningfully without redundancy.

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

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

Despite lacking an output schema, the description covers all essential aspects: what the tool does, when to use it, how it works (embeddings, windows), constraints (character cap, truncation), and output (passages with offsets and scores). It also addresses performance and integration with sibling tools.

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%, providing baseline of 3. The description adds value by explaining the embedding model and windowing mechanics for the 'query' parameter, and reiterating the character cap for 'text'. It also provides natural-language query examples, enhancing 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 purpose: 'Semantic search INSIDE a fetched record.' It uses specific verbs ('search inside'), identifies the resource ('fetched record'), and distinguishes from siblings by mentioning the pairing with ask_pipeworx_grounded and the context of searching within a single record.

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

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

Explicitly states when to use the tool: 'Use when the record is too big to cram into the prompt.' It also provides an alternative (ask_pipeworx_grounded) and explains how the tools pair together, 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 description adds significant context beyond annotations: phone verification requirement, 10/day SMS cap, auto-disable of webhook after 10 failures, and HMAC signing details. Annotations already indicate idempotentHint and non-destructive, and description aligns.

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 examples and bullet-like listings. It is slightly lengthy but each sentence contributes useful information. Minor improvement could be more paragraph breaks.

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 tool with 3 parameters, nested objects, and no output schema, the description covers requirements, type-specific parameters, delivery channels with constraints, and post-creation behavior like webhook auto-disable. It is 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?

With 100% schema coverage, the description still adds value by providing concrete examples for each subscription type and elaborating on delivery options (e.g., SMS verification, webhook signing).

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 'Create a proactive monitoring subscription to a live-data event stream' and mentions the return of a subscription ID. This distinguishes it from siblings like list_subscriptions and 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?

The description provides prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel options. However, it does not explicitly contrast with sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about the return structure (category-bucketed example questions with tool+argument shape) and the behavior when called with no arguments vs. topic, which is valuable beyond annotations.

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

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

The description is front-loaded with synonyms and clear purpose. It is slightly lengthy but every sentence adds value. A minor reduction in wordiness could be achieved, but overall it is well-structured.

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

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

Given the tool has no output schema, the description fully explains what the return data will contain (category-bucketed example questions with tool+argument shape). It also covers when to use, how to use, and the effect of the topic parameter, making it contextually 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?

The input schema has 100% coverage with clear parameter description. The description adds meaning by listing the expected topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter, thus providing additional semantic 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 explicitly states the tool's purpose as the onboarding entry point that returns category-bucketed example questions. It also distinguishes itself from sibling tools by specifying it should be used first when the agent doesn't know what Pipeworx can do.

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 guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also explains optional topic parameter and when to omit it, giving explicit instructions.

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 and non-destructive; description adds that row is deactivated not deleted, aligning with annotations and giving 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?

Two concise sentences front-load purpose and constraint, 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?

For a simple tool with one parameter, no output schema, description fully explains behavior, constraint, and side effect (deactivation vs deletion).

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 description of id as 'uuid returned by subscribe'. Tool description adds little beyond schema, meeting 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 action ('cancel') and resource ('subscription by id'), and distinguishes from sibling tools like subscribe and 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 mentions ownership enforcement ('you can only cancel your own subscriptions') and explains that deactivation preserves history via recent_alerts, providing guidance on effects.

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

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

The description goes far beyond the readOnly/idempotent annotations by detailing the dual-path internal routing (SEC EDGAR+XBRL vs grounded pipeline), explaining the meaning of each verdict, and issuing a critical warning that 'could_not_verify' must not be treated as evidence. This is rich behavioral context that structured annotations alone cannot 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 dense but every sentence contributes: trigger phrases, routing logic, verdict definitions, error semantics, and performance benefit. It is front-loaded with examples and the important caller warning, making it well-structured despite its length.

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

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

With no output schema, the description fully specifies the returned verdict set, the payload (grounded/structured actual value, citation, reasoning), and the critical error semantics. It explains both fast-path and fallback behaviors, giving callers a complete contract of what the tool will do.

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 fully described in the schema (100% coverage), so the baseline is 3. The description adds minimal parameter-specific insight beyond mentioning 'exact percent-delta math' and the tolerance override behavior, but the schema already explains tolerance_pct and its default behavior adequately.

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

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

The description opens with explicit trigger phrases ('fact check', 'verify the claim that…') and clearly defines the tool's function as natural-language claim verification against authoritative sources. It stands out from siblings by specifying the verdict output and noting it replaces 4–6 sequential calls, making it the definitive tool for this task.

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 'Use whenever the agent needs to check whether something a user said is factually correct' and distinguishes the handling of company-financial claims vs. other claims. It doesn't name specific alternative tools or exclusion scenarios, but the usage context is unambiguous and the routing guidance is clear.

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