Pdbe

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. The description adds that probing is performed on LLMs, results include per-model data, and Anthropic calls require a user-provided key and are paid directly. No contradiction, and it provides useful context beyond annotations.

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

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

The description is front-loaded with the main action and return format. At about 100 words, it is succinct but still informative. Minor redundancy: 'useful for' could be trimmed, but overall no wasted sentences.

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

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

No output schema, but the description fully details the return structure: per-model {score, confidence, signals, raw_response} plus a combined view. It also explains when to use _apiKey and context parameter. The tool has moderate complexity, and the description covers all necessary aspects.

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 4 parameters described. The description adds meaning by explaining the default model, how _apiKey enables Anthropic probing, and the purpose of context for disambiguation. This adds value beyond schema alone.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility (0-100). It specifies the default model and how to add paid models. This distinguishes it from sibling tools like ask_pipeworx or deep_research which serve different Q&A or research functions.

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

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

The description provides clear usage contexts such as AI-marketing audits, pre-launch brand checks, and competitive monitoring. It explains how to customize probing with models and API keys, but does not explicitly contrast with alternatives like deep_research or compare_entities. The guidance is strong but could be more explicit about when not to use.

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

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

Beyond the annotations, the description discloses that the tool is actually a router, not a simple retrieval method, and that it fills arguments and returns stable citeable URIs. It also implies read-only behavior by promising authoritative data with citations. The annotations already cover read-only and open-world behavior, so the description adds useful context without contradicting them.

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

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

The description is long but earned: it opens with the key instruction 'PREFER OVER WEB SEARCH', then gives a dense but useful list of query types and examples, and ends with routing to alternative tools. It could be trimmed slightly, but the length is mostly justified given the tool's broad scope and the need to guide an agent away from more expensive or more specialized tools.

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 is self-contained enough for an agent to know what to send, why this tool instead of web search or other siblings, and what kind of answer to expect. Even without an output schema, it communicates that the response is structured and comes with citation URIs. For a general natural-language lookup tool, this is quite 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 already documents the only required 'question' parameter and the five aliases. The description reinforces that input is a natural-language question and gives domain examples, but it does not add new parameter-level semantics beyond what the schema already explains. With schema coverage at 100%, 3 is an appropriate baseline score.

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

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

The description clearly states the tool's function: it routes a natural-language question to the right one of 5,596 tools across 1,465 verified sources, fills arguments, and returns a structured answer with stable pipeworx:// citation URIs. It also names the main distinction from the sibling ask_pipeworx_grounded, which is a stronger version of a single answer. This goes beyond a vague 'Ask Pipeworx' restatement and is immediately 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?

The description explicitly says 'PREFER OVER WEB SEARCH' and gives when to use it: factual, real-world, current/historical, structured data questions. It even names the specific alternative: use ask_pipeworx_grounded for a hallucination-resistant single answer with verbatim evidence, and deep_research for a broad/multi-part question. This is direct, actionable routing 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 cover safety (read-only, idempotent, non-destructive), so the description does not need to repeat those. It adds useful context: candidate routing improvements may be enabled live during tests, and the current state has no active candidate, meaning behavior can change. It also clarifies that it is a full working router rather than a placeholder.

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

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

The description is moderately concise and follows a logical order: definition, live-test status, usage, and fallback. It is mostly information dense, though 'identical' and 'same 5,596 tools, same arguments, same response shape' are slightly redundant with the initial phrase. This is not bulky enough to be penalized heavily.

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

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

The tool has a relatively small parameter surface and no output_schema, but the description explains the core behavior, the current candidate state, and how to use it. It refers to the exact response shape via ask_pipeworx rather than specifying it here, which is acceptable because that sibling tool is defined. 'A connection to return format details or error behavior' would make it fully complete.

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

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

Schema description coverage is 100%, so the baseline stays at 3 even though the description does not mention parameters. The schema's parameter descriptions are mostly repetitive aliases like 'Alias to question', which are minimally useful. The description would need to add semantics, but it does not.

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 'identical universal router' and explicitly references the same 5,596 tools and response shape as ask_pipeworx, so an agent can infer this is a query router. It separates itself from the stable ask_pipeworx by calling it the 'experimental edge.' It relies on the reader knowing ask_pipeworx for full clarity, so not all brand-new explanations.

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

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

The description explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives a clear condition for selection. It also names the stable alternative and mentions that results are compared against it. It does not spell out when to avoid this beta version, since currently it behaviorally matches the stable router.

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 important behavioral traits beyond annotations: that extraction is strictly limited to the tool result, that results include verbatim evidence and refusal reasons, and that refusal cases are enumerated. It clarifies the extra LLM call cost. No contradiction with the read-only and idempotent 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 but every sentence serves a purpose: mode, routing behavior, output shape, refusal reasons, use cases, and cost trade-off. It is front-loaded with the most important distinction and has no filler.

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

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

Despite lacking an output schema, the description explicitly defines the full response contract, including success fields, refusal reasons, and alternatives. It also connects to the sibling tool and covers parameter aliases indirectly via schema, making the tool comfortable to call correctly in both high-stakes and casual contexts.

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

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

Schema description coverage is 100%, so the schema already explains the 'question' parameter and its aliases. The tool description itself does not add parameter-level semantics, but because the schema fully covers it, this is sufficient.

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 mode ('hallucination-resistant answer mode') with a concrete behavior: route through the right tool, fetch data, then extract an answer using only tool results. It clearly distinguishes this from ask_pipe_tools and other siblings by emphasizing grounded, evidence-based answers and explicit refusals.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on... must not invent facts') and when not to use it ('prefer ask_pipe_tools for casual lookups'). It also names ask_pipe_tools as the alternative and notes the extra LLM call cost, giving clear routing 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?

Extensive disclosure of behavioral traits beyond annotations: describes resolver contract (market_match_confidence), parent event extraction, news fallback mechanisms, safety short-circuits for low-confidence/closed markets, spread warnings, and cancellation rule parsing. Annotations already indicate read-only/idempotent, and the description adds rich operational 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 very long and dense with information. While front-loaded with a clear summary, the level of detail makes it less concise. Each sentence earns its place, but the overall length could be reduced by grouping related details more tightly.

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 (multi-step fan-out, multiple edge cases), the description covers all critical aspects: input resolution, classifier list, fan-out examples, response structure, safety mechanisms, and cancellation rules. No output schema exists, but the description compensates by detailing response fields. It is complete for agents to use correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description enriches parameter meaning: for 'depth' it explains quick vs thorough, for 'include_raw' it details what raw includes and how it affects response size. It adds examples for 'market'. This extra context justifies a 4.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison). The purpose is distinct from siblings like 'ask_pipeworx' or 'polymarket_arbitrage' by focusing on comprehensive research for individual bets.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also includes when-not scenarios, e.g., low-confidence resolutions short-circuit. However, it does not explicitly name alternative tools for specific situations, which would elevate the score further.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: it makes a single parallel call, handles off-calendar fiscal years correctly, returns results sorted by primary metric, and includes citation URIs. It also describes the specific data pulled for each type. This goes well 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 concise, consisting of two sentences. It front-loads with common user queries, then efficiently conveys the tool's purpose, usage preference, data sources, and behavior. Every sentence adds value; no redundancy.

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

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

With no output schema, the description explains return data (paired data + citation URIs, sorted by primary metric). It covers entity types, data sources, and constraints. While it omits details like error handling or pagination, it provides sufficient context for an agent to use the tool effectively given its simplicity.

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 parameters are fully described in the schema. The description adds meaning by providing examples ('company' vs 'drug', tickers vs drug names), clarifying the 2–5 item constraint, and explaining the data each type retrieves. This adds context not 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 starts with natural language queries like 'Compare X and Y' and 'which is bigger / better', then explicitly states 'side-by-side comparison of 2–5 companies or drugs'. It clearly identifies the action (compare) and the resource (entities), and distinguishes itself from sequential lookups, 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 explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also explains the data sources for each entity type. However, it does not explicitly state when not to use it (e.g., for a single entity lookup).

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 transparently adds substantial behavioral context: never invents gaps, returns explicit gaps[] for unanswered facets, gives citations with stable URIs, semantic excerpting of large records, deeper time expectations for thorough mode, and the special contradictions[] for standard/thorough. No contradiction with annotations; in fact they reinforce each other.

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 contributes a necessary detail: account requirement, fallback alternative, structured research scope, decomposition strategy, return-value content, citation semantics, citation guarantee, behavior on deep data, contradictions, and time expectations. The information is front-loaded with the account warning and the core verb/resource first.

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 that there is no output schema, the description compensates fully by describing the return mechanism (findings packet with verbatim evidence, confidence, source, fetched_at, pipework:// citation, gaps[], contradictions[]), and explaining key behaviors such as large-record excerpting. It covers the only required parameter, the depth parameter's behavior, and user account limitations. Nothing essential to successful use 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?

The schema covers 100% of parameters, so the baseline is 3. The description adds semantics beyond schema by explaining that 'question' is intended to be broad/multi-part decomposition, and it enriches the meaning of the depth 'standard' value by describing the gap-recovery hop contradictions[] scan in the schema's description. Overall, knowledge is well covered both in schema and description.

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

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

The description uses a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1465 STRUCTURED data sources in ONE call', and explicitly distinguishes itself from open-web search. It names a sibling tool (ask_pipeworx) and clarifies when to use that alternative, making it completely distinct from siblings.

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

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

The description provides explicit when-to-use guidance: it states it is best for 'broad/multi-part questions over structured data', and explicitly says 'For a single lookup use ask_pipeworx instead.' It also gives a clear exclusion: if the user is not signed in, use ask_pipeworx on every tier. No ambiguity about the intended context.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds concrete behavioral details: returns tools with names, descriptions, full input schemas, and curated examples, ready to call directly. No contradictions with annotations.

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

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

The description is front-loaded with purpose, then lists domains, then explains output and usage. Every sentence adds value; no wasted words. It is efficient and well-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 complexity (6 parameters but simple aliases, no output schema), the description fully covers what the tool does and returns. It even notes that results are ready to call without a second lookup, which is critical for agent workflow.

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 6 parameters with 100% coverage, describing each as an alias for 'query'. The description adds value by explaining these aliases and providing natural language examples. Baseline 3 is slightly exceeded due to clarifying alias behavior.

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

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

The description explicitly states the tool finds tools by describing data/task, lists specific domains (SEC filings, FDA drugs, etc.), and clarifies it returns top-N relevant tools with full schemas ready to call. It clearly distinguishes itself as a discovery tool among many siblings.

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

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

The description gives explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it and its primary role in the workflow.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds rich behavioral details: parallel calls to multiple sources, soft-fail for patents after May 2025, fallback from GDELT to GNews, and provides URIs for filings. No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loaded with example queries. It efficiently covers major points but could benefit from bullet points or clearer separation of data sources and limitations. Still, no wasted sentences.

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

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

Given no output schema, the description adequately documents return fields: CIK, company_name, recent_filings with URIs, fundamentals from latest 10-K, patents (with sunset warning), news via fallback, and LEI. Minor gaps: no mention of error behavior if CIK not found or rate limits, but overall sufficient for a complex tool.

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

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

Both parameters are fully described in the schema (100% coverage). The description reinforces that value must be ticker or CIK and adds crucial guidance: 'Names not supported — use resolve_entity first if you only have a name.' This adds value beyond schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists specific data sources and returned fields, and distinguishes from siblings by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' Also mentions using resolve_entity if only a name is 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?

Explicit guidelines: use when user asks for a holistic view; if only a name, first use resolve_entity. Also advises to prefer over chaining multiple single-purpose calls. Provides examples of user queries that trigger this tool.

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

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

Annotations already indicate destructive (destructiveHint=true) and idempotent (idempotentHint=true) behavior. The description adds context about clearing sensitive data, which is valuable beyond annotations, but does not contradict them.

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

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

Two concise sentences, front-loaded with the action and resource, followed by usage and pairing guidance. No wasted words.

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

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

Given the simplicity of the tool (one parameter, no output schema, clear annotations), the description fully covers purpose, usage, and behavioral context. 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?

Only one parameter 'key' with a clear description in the schema (100% coverage). The description does not add new semantics beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'a previously stored memory by key', making the tool's action unambiguous. It also distinguishes itself from siblings by mentioning '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 the tool (context stale, task done, clear sensitive data) and suggests pairing with siblings, providing clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. No contradictions.

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

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

The description is three concise sentences, front-loaded with the purpose, and wastes no words. It effectively communicates what the tool does without unnecessary elaboration.

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 specifies the output format (standard llms.txt markdown, single text blob) and covers input parameters adequately. The tool is simple and the description is complete for its 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%, so the schema already documents both parameters. The description adds no new details beyond what's in the schema, warranting 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 tool generates an llms.txt file for a URL, specifying the verb 'generate' and resource 'llms.txt'. It distinguishes from sibling tools like 'ai_visibility_check' by focusing on a specific output format for AI crawler indexing.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It provides clear context but does not explicitly state when not to use it, which is acceptable given the focused purpose.

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

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

Beyond annotations (readOnly, openWorld, etc.), description adds key details: keyless access, source (PDBe/EBI), and return fields, enhancing transparency.

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

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

Two sentences with no waste; critical information (purpose, input, output) is front-loaded and efficiently presented.

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

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

Despite no output schema, description sufficiently describes return fields. With one simple parameter, the tool is fully specified 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 covers 100% of parameters with description, and description only reiterates the example, adding no new semantics beyond what's in 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 lists molecules/entities in a PDB structure with specific fields, distinguishing its purpose from siblings that are unrelated.

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 context on when to use (need molecule info from PDB) and input format (4-char PDB id), but lacks when-not or alternatives, though siblings are unrelated.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds useful context: no auth needed ('keyless'), and enumerates the return fields. No contradiction; it supplements the annotations well.

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 very concise—two sentences plus a brief note—while covering purpose, input, output, and source. Every sentence adds value, and key information (purpose, fields, example) is 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?

Given one parameter, high schema coverage, and annotations, the description fully covers the tool's purpose, input, and output fields. No output schema exists, but the description lists what the summary includes, making it self-contained.

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 pdb_id. The description reinforces this with an example ('1cbs'), but adds no new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool retrieves a PDB entry summary with specific fields (title, experimental method, release date, source organism, entity counts) and specifies the input format (4-char PDB ID). It distinguishes itself by naming the source (EBI) and contrasting with RCSB PDB.

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

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

The description mentions the tool is the EBI counterpart to RCSB PDB and is 'keyless', implying no authentication needed, but does not provide explicit guidance on when to use this tool over alternatives or any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds return fields and active filter context, enhancing agent understanding without contradiction.

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

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

Two sentences, front-loaded with action, no unnecessary 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 no output schema, description lists return fields. With good annotations and simple tool, it is sufficiently complete for agent invocation.

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

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

Schema coverage is 100% for the single parameter. Description mentions 'active subscriptions' but the parameter include_inactive is already described in schema. No additional value beyond baseline.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings subscribe and unsubscribe by being a read-only list operation.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an id to cancel. Does not explicitly state when not to use, but context is clear.

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

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

Beyond the annotations (all false), the description discloses important behavior: rate-limiting to 5 per identifier per day, that it's free and doesn't count against tool-call quota, that the team reads digests daily, and that filing without an account returns a claim_token for later status checks. This is valuable operational context that annotations alone do not convey.

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

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

The description is longer than average but every sentence earns its place: use cases, exclusions, claim_token behavior, rate limits, and quota impact. It is front-loaded with the core purpose and uses clear, scannable bullet-like phrasing even without bullets. Some redundancy exists (e.g., mentioning 'broken, missing, needs to exist' alongside 'bug, feature/data_gap'), but it is minor.

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 that there is no output schema and no required parameters, the description covers the main operational needs: what to submit, how to follow up, rate limits, and scope restrictions. It could be slightly more explicit about what a successful submission returns for an authenticated user, but the claim_token explanation largely fills this gap.

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%, giving the baseline 3. The description adds extra semantic value by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and reinforcing the intended use of context fields (tool, pack, vertical). It does not repeat obvious schema details.

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

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

The description opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact feedback types (bug, feature/data_gap, praise) and explicitly distinguishes from sibling tools by limiting scope to tools served by this Pipeworx connection.

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

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

The description provides explicit when-to-use triggers (tool returns wrong data, wants a new tool, etc.) and a clear when-not-to-use case: feedback about tools from other MCP servers should be filed elsewhere. It also details the claim_token follow-up workflow, giving agents a complete decision path.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: data derived from CF analytics engine, no PII, and caching behavior ('Cached 5min-1h depending on window'). No contradictions with annotations.

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

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

The description is three sentences, each earning its place: first sentence states functionality, second lists use cases, third provides technical details. Information is front-loaded and no redundant content.

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

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

Given the tool has one optional parameter with good schema description and no output schema, the description adequately covers inputs, behavior, and output (returns top tools, top packs, total call volume). No gaps for the complexity level.

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

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

Schema coverage is 100% (one parameter with enum and description). The description reinforces the parameter semantics by explaining the trade-off between window sizes, adding context beyond the schema's brief description. Could be slightly improved by mentioning default value explicitly (though it is implied).

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a recent window, which is a specific verb+resource pair. It distinguishes itself from sibling tools (e.g., discover_tools) by focusing on trending/popularity data rather than discovery.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use cases with agent behavior. It also explains when to use different window sizes ('shorter windows surface what's hot right now; longer windows show steady-state demand'). No explicit when-not-to-use, but the use cases are clear and comprehensive.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral details: partition checks, semantic anchor Jaccard threshold, partition filter with placeholder detection, fill check with CLOB depth and realizable edge, and response structure. This goes far 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 well-structured with clear organization: overall purpose, then each mode in separate paragraphs. It is front-loaded with the main concept. While somewhat verbose, the detail is justified by tool complexity. A slightly more concise summary could improve readability.

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

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

Despite no output schema, the description thoroughly details the response format (opportunities array with fields, partition_check details, fill check). It covers all major aspects of the tool's behavior across modes, making it self-contained for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: explicit examples of event slugs and topic seed questions, and explains behavior when no args are passed. This adds meaningful value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three modes (no args, event, topic) and explains each, differentiating it from sibling tools like polymarket_fill_risk and polymarket_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?

Explicit guidance is provided for when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scan. It recommends event for specific markets and explains the difference. Could be improved by explicitly stating when not to use, but overall clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint false. The description adds substantial behavioral details: three model families with specific formulas, caching behavior (1h at KV level), output structure with diagnostics, and tradeable-edge knobs. 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 long and dense, covering many details in a single paragraph. While every sentence adds value, the structure could be improved (e.g., bullet points) for better readability. It is not overly verbose given the tool's complexity, but it could be more concise.

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

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

The description thoroughly explains the output structure (by_segment, diagnostics) and caching, compensating for the lack of an output schema. It covers all aspects needed for an agent to understand the tool's behavior and return values, making it complete.

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

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

Schema description coverage is 100%, so each parameter already has a description. The tool description does not add significant meaning beyond what the schema provides; it mostly repeats or references them in context. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' and provides a use case. However, it doesn't explicitly distinguish this tool from siblings like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about when to choose this over alternatives.

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 context ('what should I bet on today') and explains knobs for filtering, but it does not provide explicit guidance on when to use this tool versus alternatives or conditions under which it should not be used. The context is clear but without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds rich behavioral context: it reads from daily snapshots with a 60-day TTL, decay numbers come from daily closes (net of slippage), not intraday, and explains the response structure in detail. 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 detailed and front-loads the core purpose, but it is somewhat verbose. The response structure is embedded within the description, which is helpful but makes it longer than necessary. It could be more concise while still providing essential details.

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

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

With no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and lists fields like first_seen, trend, decay_pp_per_day. It also covers limits (60-day TTL, snapshot gaps, decay from daily closes). This is very complete for a read-only tool with two optional parameters.

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% (both parameters described). The description adds default values (days=14, max 30; window='1wk') and explains the snapshot family concept, adding context beyond the schema definitions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on persistence and decay, not just raw edge values.

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

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

The description implies when to use the tool (to assess edge duration and decay) and gives a concrete example contrasting a fresh wide edge with an old one. It does not explicitly mention when not to use it or list alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already indicate safety. The description adds rich behavioral context: walks the order book ladder, returns a verdict (clean|degraded|cannot_fill), and explains that partial basket fills convert an arb into an unhedged directional position. It does not contradict any 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 clear sections for requirements, single-market mode, basket mode, and usage guidance. It uses bold and line breaks effectively. Every sentence provides essential information without fluff, making it comprehensive yet focused.

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

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

Despite no output schema, the description thoroughly explains all return fields for both modes, including verdict, capture_ratio, profit_usd, thin_legs, etc. It covers edge cases like forced directional risk and partial fills. For a complex tool with two modes, the description is complete and actionable.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds significant meaning: e.g., size_usd is 'max spend on buys, target proceeds on sells' for single mode and 'settlement notional — shares per leg' for basket mode; side default auto-logic is explained; event and market usage are clarified.

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 specifies the tool performs a realizable vs theoretical edge check against live CLOB order-book depth. It distinguishes between single-market and basket modes, lists specific return fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and differentiates itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into directional position). Additionally mentions requirements ('REQUIRES one of market or event') and default values.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: safety fields (compatibility_warning), temporal alignment, skipped leg comparisons, and explains when spreads are mathematically meaningless. This fully discloses behavior beyond what annotations provide.

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

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

The description is long but well-structured with clearly labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence provides necessary detail for correct usage, though it could be slightly more concise without losing essential information.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields). It covers all important aspects: modes, parameters, limitations, error conditions (compatibility_warning reasons), and temporal alignment. For a tool with 3 optional params, this is exceptionally 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 each parameter has a description. The tool description reinforces the parameter meanings and explains how they interact (e.g., explicit tickers override topic). This adds context beyond the schema alone, justifying a score above the baseline 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 explicitly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from siblings by focusing on cross-venue comparison, and explains two modes (topic shortcuts and explicit tickers) with clear examples.

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

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

The description provides explicit guidance on when to use each mode: topic for 10 pre-mapped macros, explicit tickers for custom pairings. It also advises that real cross-venue spreads are rarer than the shortcut list suggests and that pre-mapped does not mean tradeable, effectively telling the agent when results are not reliable.

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

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

Annotations already declare readOnlyHint and idempotentHint true. Description adds value by explaining scoping to user identifier and pairing with remember/forget. 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?

Three concise sentences front-loaded with main action. Every sentence adds value. No wasted words.

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

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

Given one optional parameter, no output schema, and robust annotations, the description fully covers purpose, usage, scoping, and pairing with siblings. Complete for a simple retrieval 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 description coverage is 100% for the single optional parameter, and the description restates the same behavior (omit to list all keys). No additional meaning beyond schema.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys', using specific verbs and resource. Differentiates 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?

Provides explicit usage context: 'look up context the agent stored earlier' with examples. Mentions scoping and pairing with remember/forget. No explicit when-not, but context is clear.

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

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

Discloses optional state modification via mark_read, which might contradict readOnlyHint annotation but is transparently described. Adds polling suitability and alternative access, going beyond annotations.

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

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

Three sentences, front-loaded with purpose, then returns, then filters. 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?

Despite no output schema, description covers return structure, parameter details, side effects, and alternative access. Completely adequate for a read-oriented tool with good annotations.

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

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

Schema provides full parameter descriptions (100% coverage). Description adds minimal context: example for type, format for since, default for mark_read. Meets baseline but doesn't significantly enhance.

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

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

Clearly states action (pull) and resource (fired events from subscription feed). Includes specific return fields (source, citation_uri, raw payload), distinguishing it from sibling tools like 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?

Provides usage tips: filtering by type and since, mark_read to update state, and notes that polling is fine. Mentions alternative access via GET endpoint for scripts. Lacks explicit when-not-to-use but overall helpful.

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

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

Annotations indicate readOnly, idempotent, nondestructive. Description adds detailed behavior: fans out to SEC, GDELT/GNews fallback, USPTO soft-fail, and return structure (changes grouped by source, total_changes, pipeworx URIs). No contradiction.

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

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

Concise yet dense: examples at start, then sources, fallback, soft-fail, parameter guidance, return structure, and sibling comparison. No wasted words, well 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 complexity (multi-source, fallback, soft-fail, no output schema), the description covers all necessary context: sources, fallback behavior, date formats, return shape, and when to use alternative 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 covers all three parameters with descriptions. Description adds extra guidance: relative date shorthand for `since`, ticker/CIK examples for `value`, and that `type` is only 'company'. Adds meaningful value beyond schema.

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

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

The description clearly states this tool provides a change feed ('What's new with X') for a company in the last N days, fanning out to multiple sources. It distinguishes from sibling `entity_profile` which is for static profile.

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

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

Provides explicit use cases ('What's new', 'latest on', etc.) and directs agents to use `entity_profile` for static profile. Also advises on using relative dates like '30d' for typical monitoring.

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

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

Annotations indicate idempotent and non-destructive. The description adds context about retention periods (persistent for authenticated, 24h for anonymous) and scoping by identifier, enhancing understanding 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 focused paragraph of 5 sentences, front-loaded with purpose, followed by usage guidance and technical details. No redundant information.

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

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

For a simple store tool, the description covers purpose, usage, persistence, and pairing with siblings. Lack of output schema details is acceptable as return values are likely trivial or implied.

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

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

Schema coverage is 100%. The description adds naming conventions and examples for key-value pairs, providing marginal extra value 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 saves data for reuse across conversations/sessions, specifies key-value storage, and distinguishes 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?

The description explicitly lists when to use the tool (e.g., discovered tickers, preferences) and covers scope and persistence differences, though it doesn't explicitly 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?

Beyond annotations (readOnly, openWorld, idempotent), the description discloses graceful degradation (LEI/FIGI enrichment if unavailable still returns EDGAR identifiers), internal cascading lookups, and explicit handling of unresolved identifiers under 'unresolved'. This provides 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 longer than average but well-structured with SUPPORTED TYPES and examples. Each sentence adds necessary detail; however, some compactness could be achieved without losing key information. Front-loaded with examples and purpose.

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

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

The description fully explains return behavior (identifiers with source labels, unresolved list), input variants, fallback behavior, and internal cascading. Without an output schema, it compensates thoroughly, making the tool's behavior predictable.

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

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

Schema coverage is 100%, but the description adds substantial value: concrete examples (AAPL, 0000320193, ozempic), explains ISIN-to-LEI mapping for company type, and clarifies that drug accepts brand or generic name. It transforms parameter usage from abstract to practical.

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 resolves user-spoken names to canonical/official identifiers, with specific examples like 'What's the ticker for…' and explicit supported types (company, drug). It distinguishes from siblings like entity_profile and compare_entities by focusing on name-to-ID resolution.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. However, it does not provide when-not-to-use conditions or name alternatives explicitly, though the examples imply a clear use case.

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 specific behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. No contradictions with annotations.

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

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

The description is three sentences, front-loading the purpose in the first sentence. Second sentence adds detailed behavior. Third sentence gives a concrete example. No wasted words, 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 4 parameters, no output schema, and schema coverage is 100%, the description provides sufficient context: explains the workflow, return format, and use case. It could mention entity count constraints (2-8), but that's in the schema. Overall complete for its complexity.

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

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

Schema coverage is 100%, so the description adds minimal extra meaning beyond the schema. It mentions 'your brand + N competitors' implying the first entity is the subject, which is a slight addition. Otherwise, the schema already describes each parameter 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 clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks them, and surfaces most/least recognized. This distinguishes it from the sibling ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description gives a clear use case ('competitive AI-marketing audits') and an example question. It does not explicitly state when not to use or list alternatives, but the context implies it is for side-by-side comparison, which is sufficiently clear.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by disclosing that bundlephobia's first measurement may take 5-30 seconds and that failures degrade gracefully with a 'sources_failed' field. No contradiction with annotations.

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

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

The description is a single paragraph that front-loads the core purpose, then provides details. While it is longer than some, every sentence adds value (usage guidance, behavioral notes, return format). Slightly verbose but not wasteful.

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

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

Despite lacking an output schema, the description thoroughly explains the return value: summary block with listed fields, per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timeouts, ensuring the agent knows what to expect.

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

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

Input schema has 100% description coverage for both parameters (package and version). The description adds minor context about scoped packages and default version, but does not significantly enhance the schema's clarity. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a composite check for evaluating npm packages, listing the specific data sources (deps.dev and bundlephobia) and the criteria checked (license, advisories, bundle size, etc.). It distinguishes from sibling tools by explicitly limiting to npm ecosystem in v1 and directing other ecosystems to deps.dev:version.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies when not to use (other ecosystems) and notes partial failures and timeouts, helping the agent decide appropriately.

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

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

Goes beyond annotations by specifying embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), and truncation behavior (200K char cap with flag). Annotations already declare safety properties; description adds technical detail.

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

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

Four sentences, each adding unique value. Front-loaded with purpose, no redundancy. Efficiently covers usage, behavior, and technical details.

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

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

No output schema, but description explains return format (passages with offsets and scores). Covers input constraints, truncation, and pairing with a sibling tool. Complete for a search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing query examples and clarifying the 'limit' default and range, plus embedding details that inform parameter 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 'semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by highlighting context-saving, character offsets, and pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and mentions pairing with ask_pipeworx_grounded. Provides clear context for when to use, though does not explicitly list 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 provide readOnly=false, idempotent=true, etc. The description adds context such as OAuth requirement, sms/day cap, webhook auto-disable, and per-type parameter details, which enriches behavioral understanding 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 detailed yet well-structured, front-loading the core purpose and then layering specifics. Every sentence adds value, though there is slight redundancy with the schema's delivery description.

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 mentions return of subscription ID. It covers all parameter types, delivery channels, and constraints, making it sufficiently complete for the tool's complexity.

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

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

Schema has 100% coverage with descriptions for all parameters. The description adds concrete examples (e.g., items:["5.02"], topic:"fed") and delivery constraints (e.g., sms must match verified phone), providing 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 creates a proactive monitoring subscription to live-data event streams, specifies return of a subscription ID, and lists event types, distinguishing 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?

It explicitly requires a Pipeworx OAuth account and states that anonymous/BYO cannot persist subscriptions, implying when to use. It details delivery channel constraints but does not explicitly contrast with sibling tools like list_subscriptions or recent_alerts.

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 aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), adding important behavioral context: it returns live catalog data with exact tool and argument shape, and explains the difference between no arguments and topic-specific calls. No contradictions with annotations.

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

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

The description is well-structured and front-loaded: it starts with alternative phrasings and purpose, then describes the return type and usage. It is moderately concise, with no wasted sentences, but could be slightly shorter while retaining all 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 optional parameter, no output schema, but with rich annotations), the description provides complete context: categories, usage patterns, return content, and relation to other tools. It fully covers what an agent needs to know to use this tool effectively.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the effect of omitting the parameter ('cross-category spread') and listing the allowed topic values, going beyond the schema's basic description.

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

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

The description clearly states that this tool is an onboarding entry point for a new agent to learn about Pipeworx. It uses specific verbs ('returns category-bucketed example questions') and distinguishes from siblings like ask_pipeworx and discover_tools by detailing the exact content and purpose.

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

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

The description explicitly advises to use this tool first when you do not yet know what Pipeworx can do, and explains how to call with no arguments for a full spread or pass a topic to focus. While it doesn't explicitly state when not to use it, the context is clear and sufficient.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it is keyless (no authentication needed), sourced from EBI, and returns specific data (chains and residue range). 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 two sentences and front-loaded with the main purpose. The first sentence is dense but conveys all essential information without waste. Minor verbosity is acceptable.

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

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

For a simple one-parameter tool with rich annotations, the description fully covers the source, output format, keyless access, and example. No output schema exists, but the description explains return values sufficiently.

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 for the single parameter (pdb_id), with a clear description and example. The description reinforces the 4-char format and example, adding no new semantics beyond the schema.

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

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

The description clearly states the tool performs SIFTS cross-database mapping from PDB to UniProt, specifying the source (PDBe/EBI), output details (matching chains and residue range), and a concrete example. It distinguishes from siblings by emphasizing 'curated cross-database mappings unique to EBI.'

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 (mapping PDB to UniProt) and implies authoritative curation, but does not explicitly state when not to use this tool or mention alternative tools for similar mappings. No exclusion criteria are given.

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 ownership enforcement and deactivation behavior beyond annotations. Annotations already indicate non-destructive and idempotent; description adds context that historical events remain available and links to 'recent_alerts'.

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

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

Two sentences, no wasted words. Action is front-loaded. Every sentence adds meaningful information.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, idempotency, deactivation, and data retention. No gaps for agent usage.

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

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

Schema coverage is 100% with description of 'id' parameter. Description adds value by clarifying that the id is 'returned by subscribe', providing useful linkage. Avoids redundancy.

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 'cancel a subscription by id' with specific verb and resource. It distinguishes from deletion by noting 'deactivated (not deleted)' and references sibling tools like 'subscribe' and 'recent_alerts'.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, but does not explicitly contrast with alternatives like 'unsubscribe' vs 'delete' (though no delete tool exists). Guidance is sufficient.

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

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

Beyond the annotations (read-only, open-world, idempotent), the description discloses critical behavioral nuances: the dual pipeline (structured SEC EDGAR vs. grounded fallback), the exact verdict vocabulary, and the vital distinction between 'could_not_verify' (check failed) and 'unsupported' (no source coverage). It also warns callers not to treat 'could_not_verify' as evidence, adding significant value not present in 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 yet efficiently structured: it front-loads with natural-language triggers, then explains usage, return value, and important exceptions. Every sentence earns its place, covering routing, verdicts, citations, and error handling without 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?

There is no output schema, so the description must fully explain return values and behaviors. It does so thoroughly: verdict types, actual value with citation, reasoning, and the semantic distinction between 'could_not_verify' and 'unsupported'. It even notes the tool replaces multiple sequential calls, giving a full picture of the tool's role and expectations.

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

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

The input schema already provides 100% coverage with detailed descriptions for both 'claim' and 'tolerance_pct', including the override behavior and default cap. The description adds example claims but no new semantic information beyond what the schema states, so it does not elevate beyond the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides example queries ('Is it true that…', 'fact check') and explicitly distinguishes it from general research tools by focusing on fact-checking user statements. The scope 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?

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct', giving a clear trigger condition. It also details the internal routing for company-financial vs. other claims, which explains when one path is preferred. However, it does not name alternative sibling tools or provide explicit 'when not to use' exclusions, so it falls just short of a 5.

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