Mesh

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds value by disclosing cost implications (free default, BYO Anthropic), the pass-through of API key, and the structure of the response (per-model fields). 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 but packs purpose, default behavior, optional usage, output format, and use cases. Every sentence is informative, no redundancy, and the most critical information (what and default) 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?

Despite no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view). The safety profile is covered by annotations. With 4 parameters fully detailed, the description is complete for correct tool 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% with descriptions for all 4 parameters. The description adds further context: default model, relationship between 'models' and '_apiKey', and how 'context' disambiguates. This goes beyond schema details, making parameter semantics fully clear.

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

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

The description uses specific verbs ('probe', 'score visibility') and clearly identifies the resource ('LLMs') and output (visibility score 0-100). It distinguishes from siblings by focusing on AI visibility auditing, which is not covered by other tools like 'scan_competitor_ai_presence' or 'deep_research'.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains model selection with default vs. API key. It does not explicitly mention when not to use or list alternatives, but the context is sufficient for agent decision-making.

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 describe the tool as read-only, idempotent, non-destructive, and open-world. The description adds value by disclosing that it fills arguments automatically, routes internally across thousands of tools, and returns stable pipeworx:// citation URIs. It does not contradict any annotation and gives enough behavioral context beyond what annotations declare.

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 ideal but front-loads the most critical instruction ('PREFER OVER WEB SEARCH') and packs the rest into a single coherent block. Every sentence contributes either usage trigger, evidence of behavior, or an example. It is lengthy but 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?

The description tells the agent what the tool returns (structured answer with stable pipeworx:// URIs) even without an output schema, and explains when it should be selected over web search, grounded mode, and deep research. The tool only has one required parameter, so the context around its use and return value is more than sufficient to call it correctly.

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

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

The input schema has 100% coverage: every parameter is documented as an alias of 'question'. The description supplements this with concrete question examples and a broad list of topical domains, which helps the agent formulate a correct and relevant value to pass. While the schema already handles meaning, the examples add practical guidance.

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 routes a user's natural-language question to the right one of 5,596 tools across 1,465 verified sources and returns a structured answer with citations. It uses a specific verb ('routes'), defines the resource, and differentiates itself from both web search and sibling research tools. This leaves no doubt about what the tool does.

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

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

It explicitly says 'PREFER OVER WEB SEARCH' and lists trigger phrases and example questions, telling the agent when to favor this tool. It also names alternatives for specific cases (ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions), so the agent knows when not to use this tool. This is an explicit when/when-not/alternatives setup.

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 well beyond the annotations by explaining the live experimental nature, that no candidate is currently active, that it matches ask_pipeworx exactly right now, and that there is no fallback. This discloses the dynamic behavior an agent needs to know when deciding to invoke this experimental edge.

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, all substantive, with the core beta-version identity front-loaded. It is somewhat dense but each sentence earns its place and flows logically from identity to state to usage to fallback.

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

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

Covers current status, comparison to the stable route, usage instructions, and fallback behavior, while pointing to 'same response shape'. Even without an output schema, an agent has enough context to call it appropriately and interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only says 'same arguments' as ask_pipewor without adding any new parameter-level detail or clarifying semantics beyond what the input 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?

Explicitly identifies the tool as the beta version of ask_pipeworx and a universal router with the same 5,596 tools, arguments, and response shape. This clearly conveys the tool's function and distinguishes it from the stable ask_pipeworx sibling.

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 direct usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that when no candidate is active, behavior matches the stable router exactly. It names the alternative ask_pipeworx, though it does not explicitly state 'do not use when stability is preferred.'

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 readOnly/idempotent/non-destructive annotations, the description discloses the full refusal schema, the extraction constraint 'EXTRACTS the answer using ONLY what the tool result contains', the exact return fields, and the extra cost. This gives an agent a complete mental model of success and failure behavior.

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 critical purpose and safety-quality indicator, then follows a logical order: mechanism, return shape, refusal cases, usage guidance, cost trade-off. Every sentence contributes useful, specific information, with no fluff.

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

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

Since there is no output schema, the description fully specifies the return type with fields and refusal reasons. It also covers when/how to invoke, cost comparison, and alternative tool. The annotations cover the safety profile and idempotence, so no essential operational information is missing.

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

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

The input schema covers 100% of the six parameters with clear descriptions, including aliases and natural-language guidance. The tool description does not add meaningful parameter semantics beyond saying 'fills arguments'; thus the baseline of 3 is appropriate.

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

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

The description clearly defines a distinct grounded-answer mode: 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of picking tools, fetching data, and extracting answers only from the tool result. It differentiates itself from ask_pipeworx by emphasizing evidence-based, refusal-ready behavior, so an agent can see exactly what the tool does and how it differs from its 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?

Use conditions are explicit: 'Use whenever an answer will be quoted, cited, or acted on' and for domains requiring factual integrity (financial, legal, medical, public statements). The when-not-to-use is also clear: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call, and refusal reasons define when the tool should not return an answer.

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

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

Annotations indicate read-only, idempotent behavior, which the description aligns with. It extensively details safety mechanisms (low-confidence short-circuit), response shapes, and resolution-rule risk, adding significant 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 comprehensive but very long (over 500 words). It is well-structured with sections and front-loaded with the core purpose, but 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?

Given the tool's complexity (3 params, no output schema), the description is exceptionally complete, covering resolver contract, parent event extractor, news fields, and error handling, leaving no ambiguities 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%, so baseline is 3. The description adds value by explaining depth options ('quick = 2-3 evidence sources') and include_raw consequences, enhancing parameter understanding.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with explicit verb and resource ('Research a Polymarket bet'). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on data gathering and analysis for a single bet.

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 ('Use for "should I bet on X"...') and describes behavior in various scenarios (low confidence, closed markets). Lacks direct when-not-to-use or alternative tool mentions, but the context is sufficient.

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

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

Annotations declare readonly, open-world, idempotent, non-destructive. Description adds that it makes a single parallel call, handles off-calendar fiscal years correctly, sorts results by primary metric, and returns citation URIs. No contradictions.

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

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

Single paragraph, front-loaded with trigger phrases, every sentence adds value. No wordiness.

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 explains return data (paired data + citation URIs) and covers edge cases (off-calendar fiscal years). Complete for an agent to use correctly.

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

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

Schema has 100% coverage, baseline 3. Description adds meaning by explaining 'tickers/CIKs' for company type and 'drug names' for drug type, gives examples, and notes that results are sorted by primary metric, helping agents understand output ordering.

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

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

Description clearly states it performs side-by-side comparison of 2–5 companies or drugs, using specific trigger phrases like 'compare', 'vs', 'rank'. Distinguishes from single-entity lookups (entity_profile) by emphasizing batch comparison.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries that should invoke this tool (e.g., 'which is bigger', 'rank these companies'). Also notes it replaces 8–15 sequential lookups.

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

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

The annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description builds on that with real behavioral context: account/tier gating, latency 15-90s, gap[] and contradiction[] semantics, a never-invented guarantee, and a hop/citation_uri contract for fetched evidence. Credit for the depth; the purple text still contains slightly garbled substrings, so not a 5.

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 packs many kinds of content: auth prerequisites, execution model, return format, examples, latency, and the failure-mode behavior. No sentence is entirely wasted, but there is duplicate coverage of gaps/contradictions (schema vs prose) and some garbled or mis-embedded substrings that make the structure feel cluttered.

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 complex tool with no output schema, the description essentially defines the full contract: the findings packet shape, evidence+confidence+source+timestamp, citation_uri servability constraint, gaps[], contradictions[], and hop field. With auth, latency, and when-to-route elsewhere also covered, an agent is well equipped. The garbled bits and repetition prevent a 5.

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%: both question and depth are already fully described in the input schema, which is the baseline-3 case. The description adds only collaterals (decomposition hint, thorough requires the paid plan), which is helpful but not substantive new semantics for either parameter.

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

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

The description states a specific verb and resource: grounded multi-source research across Pipeworx's 1465 structured data sources in ONE call. It explicitly differentiates itself from siblings and open-web search ('this is NOT open-web search', 'For a single lookup use ask_pipeworx'), so an agent can tell what it is and what it is not.

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?

Use conditions are explicit and name the alternative tool: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'Best for broad/multi-part questions over structured data'. This goes beyond saying when to use it into saying when not to and which sibling covers the other 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 declare readOnlyHint=true and idempotentHint=true, but the description adds value by explaining that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas' and that each result is 'ready to call directly, no second schema lookup needed.' This clarifies the behavioral output and workflow 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 core purpose and use cases. Each sentence contributes meaningful information without excessive verbosity. However, it is slightly longer than necessary for the amount of information conveyed.

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

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

Given the tool's complexity (6 parameters, no output schema, no nested objects), the description is complete. It explains what the tool returns (tools with schemas) and how results can be used directly. With no output schema provided, the description adequately covers the return value behavior.

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

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

Schema coverage is 100%, and parameter descriptions in the schema are already clear (e.g., 'Natural language description of what you want to do'). The description adds some context by listing example domains (SEC filings, financials, etc.), but adds no critical information beyond the schema's own descriptions and examples.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and distinguishes itself from sibling tools by explicitly guiding the agent to 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description provides explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST...' It clearly indicates when to use this tool versus alternative tools, though it does not explicitly exclude use cases.

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 further behavioral context: fans out across multiple sources, soft-fails on patents (USPTO API sunset), uses GDELT→GNews fallback, and details the returned fields. 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 front-loaded with example user intents and is comprehensive. It is slightly verbose but every sentence serves a purpose, explaining the fan-out, return structure, and edge cases. Could be slightly more concise, but still efficient.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains what is returned (cik, filings, fundamentals, patents, news, LEI) with details. It covers key behavioral aspects like fallback and soft-fail. The context is complete for an AI agent to understand the tool's output.

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

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

Schema descriptions cover 100% of parameters. The description goes beyond by providing examples (e.g., 'AAPL' or '0000320193'), enumerating the supported types, and clarifying that names are not supported. It also hints at future support for person/place.

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: providing a holistic cross-source profile of a US public company. It uses example queries like 'Tell me about X' and lists specific data sources and return fields. It differentiates from siblings like resolve_entity by explicitly stating to use that tool for name resolution.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' when the user asks for a holistic view. Provides clear input requirements (ticker or CIK) and warns against using names, directing to resolve_entity. This gives strong guidance on when and how to use.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description confirms deletion and adds context about sensitive data, but doesn't disclose additional behavioral traits 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?

Two short sentences, no wasted words, front-loaded with clear action.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage context, and pairing with related tools.

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

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

Schema has 100% coverage for the single parameter 'key', so description adds marginal value (e.g., 'by key' phrase). 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?

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource, distinguishing it from siblings '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 (stale context, done task, clear sensitive data) and pairs with 'remember' and 'recall', 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, openWorldHint, idempotentHint, and destructiveHint as false, indicating a safe, non-mutating operation. The description adds valuable context by detailing the process (fetches page, extracts title/description/key links, emits standard markdown format), confirming the behavior without contradiction.

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

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

The description is three sentences, front-loaded with the core purpose and output, followed by process and use cases. Every sentence adds value without redundancy or 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 tool's low complexity (2 parameters, no output schema, no nested objects, comprehensive annotations), the description fully covers what the agent needs: what it does, how it works, and the output format ('single text blob' in standard markdown). 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?

Input schema has 100% description coverage, so baseline is 3. The description does not add additional semantic meaning beyond the schema, only reaffirming the output format. No extra detail on parameters like URL format or max_links behavior beyond existing 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 generates a production-ready llms.txt file for a URL, specifying the action, resource, output format, and benefiting AI crawlers. It is specific and distinct from sibling tools like 'scan_competitor_ai_presence' which focuses on auditing rather than generating.

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: indexing a client's site, drafting for own projects, auditing competitor visibility. This provides clear context for when to use the tool, but does not mention when not to use it or alternative tools, though the specificity makes exclusions less necessary.

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, and open-world. The description adds value by listing the specific fields returned and noting the tool is 'Keyless' (no authentication). For a simple retrieval tool, this is sufficient.

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 and resource. Every sentence adds meaningful information without redundancy.

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

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

No output schema, but the description covers the main return fields. It does not mention error handling or what happens with invalid IDs, but for a simple get-by-ID tool, the description is largely 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 baseline is 3. The description adds context beyond the schema by providing examples and clarifying the format of the mesh_id parameter (e.g., 'D003920' = Diabetes Mellitus).

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

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

The description clearly states the action ('Get'), the resource ('MeSH descriptor'), and what is returned (preferred label, entry terms, qualifiers, see-also). The example ID 'D003920 = Diabetes Mellitus' and the phrase 'by its ID' differentiate it from sibling search tools like search_descriptors.

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

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

The description implies use when you have a specific MeSH ID, providing examples of ID format. However, it does not explicitly state when not to use it (e.g., use search_descriptors if you don't have an ID).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that results are caller-specific and lists return fields, which supplements the annotations without contradiction.

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

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

Three concise sentences with front-loaded action and no extraneous information. Every sentence serves a purpose.

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

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

The description lists return fields and provides usage guidance. With annotations and a simple parameter, it is sufficient for correct invocation, though potential pagination or limits are not mentioned.

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

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

The single parameter 'include_inactive' is fully described in the input schema (100% coverage). The description does not add meaning 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 tool lists the caller's active subscriptions and enumerates return fields. It is distinct from sibling tools 'subscribe' and 'unsubscribe'.

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

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

The description advises using it to review monitored subscriptions before adding more or to find an id to cancel, providing clear context. It does not explicitly mention alternatives, but the sibling tools imply when not to use this tool.

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

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

Beyond annotations (readOnlyHint: false, destructiveHint: false), the description discloses important behaviors: filing without an account returns a claim_token, how to pass it back later, rate limiting (5/day), that it's free and doesn't count against quota, and that the team reads digests daily. These add significant context not captured by annotations.

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

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

The description is long but efficiently structured, with each sentence contributing essential information (purpose, usage rules, exclusions, claim flow, rate limits). It front-loads the core purpose and then provides necessary detail. It is not wasteful, though somewhat dense; a 4 reflects this balance.

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 feedback tool with 4 parameters, all documented in the schema, and no output schema, the description thoroughly explains the request/response flow (claim_token), constraints (rate limit, quota), and appropriate content. It fully addresses the tool's complexity, leaving no significant gaps for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the claim_token workflow (pass only the token with no other arguments) and provides a concise summary of the type enum semantics. This goes beyond the schema's field descriptions, meriting a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and explicitly differentiates from siblings by restricting to Pipeworx tools and naming the alternative (file with the other server). This is a specific verb+resource with clear scope.

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

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

Provides explicit when-to-use instructions for each case (bug, feature/data_gap, praise) and explicit when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' It also tells users to describe issues in terms of Pipeworx tools and not to paste end-user prompts. This fully covers usage context and 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 declare readOnly, idempotent, openWorld, non-destructive. Description adds sourcing (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and confirms aggregation method, going well 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?

Five sentences, front-loaded with purpose and use cases, no wasted words. Could be slightly tighter but 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 simplicity (1 param, no required, full schema coverage, rich annotations), description explains return contents, parameter rationale, caching, and privacy. No output schema but return type is clear.

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 'window' with 100% schema description coverage. Description does not add new details beyond schema's enum explanation of hot vs steady-state; baseline 3 applies.

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

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

Description specifies verb 'Returns' and resource 'top tools, top packs, total call volume' over a recent window. Clearly distinguishes from siblings like 'discover_tools' by focusing on trending data rather than general 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?

Three explicit use cases (discovering hot data, confirming canonical tool, aligning with agent needs) plus guidance on window selection. No explicit when-not-to-use, but context 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral detail: algorithmic checks (monotonicity, partition sum), Jaccard similarity filter, placeholder partition filter, fill check against CLOB depth, and output structure. No contradiction.

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

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

Description is long but well-structured and front-loaded with purpose and modes. Every sentence adds value, though some redundancy could be trimmed. Still, it remains clear and 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?

Despite no output schema, the description thoroughly explains response fields (opportunities[], partition_check, fill check), edge cases (Jaccard similarity, placeholder filters), and cross-tool integration (fill risk). Complete for a complex arbitrage tool.

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

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

Schema coverage is 100% with both parameters described. Description adds significant meaning: explains event slug format, topic as seed question, mode activation, and additional accepted formats (full URLs). Goes well 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 it finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It distinguishes three modes (trending, event, topic) and contrasts with sibling tools.

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

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

Explicit guidance for each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also warns not to trade when fill check yields realizable_edge_pp ≤ 0, and suggests polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, which the description does not contradict. The description adds rich behavioral context: cached 1h, model families, diagnostic output, and edge-case handling (Fed bets). This adds significant value beyond annotations.

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

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

The description is comprehensive but quite long (over 400 words) and could be more concise. However, it is well-structured with sections, bullet points, and front-loaded purpose, earning an average score for conciseness.

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

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

Given the complexity (9 parameters, no output schema), the description fully explains the return structure (by_segment, diagnostics, fed_note), edge cases, and knob effects. It compensates for the lack of output schema by detailing response fields and interpretation.

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%, yet the description provides additional context for each parameter, such as default values, usage examples, and rationale (e.g., slippage_pp explains zero fees but bid/ask depth). This goes beyond the schema descriptions, making parameter semantics excellent.

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 scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is specific about the resource and action, and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 positions the tool for 'what should I bet on today' and explains knobs like min_liquidity, max_spread_pp for tradeability filtering. However, it does not explicitly contrast when to use this vs. sibling tools like polymarket_arbitrage, so some implicit guidance is missing.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds detail about snapshot TTL (60 days), cache-miss-based snapshot creation, and decay calculation from daily closes, providing useful behavioral context beyond annotations.

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

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

Well-structured with sections for Args, RESPONSE, LIMITS. Front-loaded with purpose. Slightly verbose but every sentence contributes 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?

Despite missing output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their semantics. Covers limitations like TTL and data gaps. Could mention error handling or parameter validation briefly.

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 documented in schema (100% coverage). Description adds context on defaults (14 days, '1wk'), constraints (max 30), and explains how they affect the response (lookback, snapshot family). Also describes response structure that relies on parameters.

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

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

Clearly states it provides edge persistence and decay telemetry from daily snapshots. Answers the specific question about edge longevity. Differentiates from sibling polymarket_edges by focusing on time-series and decay.

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?

Implies usage context (comparing fresh vs old edges) but does not explicitly state when to use this tool versus sibling polymarket_edges or when not to use it.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent. Description adds detailed behavioral context: returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and explains risks of partial fills and unhedged positions.

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

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

Description is lengthy but well-structured with labeled sections (SINGLE-MARKET, BASKET) and lists outputs. Every sentence adds value, though could be slightly more concise. Front-loaded with purpose.

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

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

Given complexity (two modes, many return fields, no output schema), description thoroughly explains inputs, outputs, and edge cases (thin_legs, forced_directional_risk). Complete for safe and effective tool 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%, but description adds significant meaning: explains market vs event modes, side defaults and auto behavior, size_usd interpretation for buys vs sells and basket mode, and clamp range (10–1,000,000).

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes single-market vs basket modes. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by specifying that it is a risk check before executing trades.

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

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

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns about non-capturable theoretical overround on thin books and risk of partial basket fills converting arb to directional position.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral detail: compatibility_warning conditions (bet shape mismatch, unrelated events), temporal alignment signals, skipped cross type/subtype counters, and the response structure (leg-by-leg prices, top_spreads_pp). 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 thorough but not overly verbose. It is front-loaded with the core purpose and then structures details by mode and safety fields. Every sentence adds information. Minor verbosity in the explanation of compatibility_warning could be trimmed, but overall it is well-organized and efficient.

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

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

Despite no output schema, the description comprehensively covers return fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases (non-equivalent bet shapes, unrelated events, temporal misalignment). For a complex tool with multiple modes and safety checks, this is a complete description.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic context beyond the schema: for 'topic' it lists the 10 shortcuts, for 'kalshi_event_ticker' and 'polymarket_event_slug' it explains they override the topic-mapped side. This helps the agent understand parameter interactions and valid values, adding clear value.

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

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

The description clearly states the tool's purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies two modes (topic shortcuts and explicit tickers) and contrasts with sibling tools like polymarket_arbitrage, which focuses on intra-venue arbitrage. The verb 'spreads' and resource 'cross-venue' are specific and distinctive.

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

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

The description explains when to use the tool (to find cross-venue spreads) and warns that most pre-mapped topics return compatibility warnings, indicating when results may not be actionable. It also explains parameter overrides. However, it does not explicitly state when not to use it (e.g., if the user needs only one venue's data), though the context of sibling tools makes this 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 declare readOnly and idempotent. Description adds scoping to identifier and behavior when key omitted, providing extra 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?

Concise, multi-sentence paragraph with clear structure: action, examples, scoping, complementary tools. No extraneous information.

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

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

Lacks specification of return format or error handling (e.g., what happens if key not found). With no output schema, description could better describe the response structure.

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 and description adds context for omitting key (list all). The description enriches understanding by explaining typical use cases.

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

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

Description clearly states the tool retrieves a saved value or lists all keys, using specific verbs ('retrieve', 'list') and distinguishes from sibling tools '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 when-to-use examples (look up stored context) and mentions pairing with remember/forget. Lacks explicit 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds concrete behavioral details: return fields (source, citation_uri, payload), mark_read side effect, and that polls work fine. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, followed by details. Every sentence adds value with no redundancy. Well-structured and 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?

Despite no output schema, the description covers return payload details, filtering options, mark_read behavior, and alternative access method. It is complete for a read-only polling tool with good annotations.

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

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

Schema coverage is 100% with descriptions. The description adds value by giving examples (type 'sec_8k', ISO timestamp) and explaining mark_read behavior ('flag returned events read so the next call only shows newer ones'). This enriches understanding beyond the schema.

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

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

The description clearly states the verb 'pull' and resource 'fired events from your subscription feed'. It distinguishes the tool as a read operation for recent alerts, but does not explicitly differentiate from sibling tools like 'list_subscriptions' or '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?

The description provides clear usage context: filter by type and/or since, mark_read behavior for polling, and mentions an alternative access method via GET registry.pipeworx.io/alerts.json. It does not explicitly state when not to use this tool or compare to siblings.

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

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

Beyond the annotations (readOnlyHint, etc.), the description details the parallel fan-out to multiple sources, the GDELT→GNews fallback mechanism, the soft-fail for USPTO due to API sunset, and the return structure (changes by source, total_changes count, citation URIs). It fully discloses behavioral traits.

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, front-loading with example queries to quickly convey purpose. It is reasonably concise given the complexity, though slightly verbose with multiple example queries. Every sentence adds value.

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

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

Given the lack of an output schema, the description thoroughly explains the tool's behavior: sources used, fallback logic, soft-failures, and return format (structured changes, total count, citation URIs). It also clearly distinguishes from the sibling entity_profile, ensuring complete contextual understanding.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces parameter types and formats but does not add significant new meaning beyond the schema's own descriptions. It provides minor usage guidance (e.g., typical 'since' values) but not deeper semantics.

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 clear query examples ('What's new with X', 'latest on Y') and explicitly states it returns a change feed for a company over a time window, listing specific data sources. It distinguishes from sibling tool entity_profile, which is for static profiles regardless of window.

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: when to use (for recent changes over a window), when not to (use entity_profile for static profile), and usage tips for the 'since' parameter ('Use '30d' or '1m' for typical monitoring'). It also names an alternative 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 provide idempotentHint=true and destructiveHint=false; description adds scoping by identifier and persistence duration, which are valuable behavioral details beyond annotations.

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

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

Two dense sentences front-loaded with purpose, examples, and usage context. Every sentence earns its place with no wasted words.

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

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

With 2 simple parameters, no output schema, and annotations covering idempotency, the description provides complete guidance on when and how to use, retention, and pairing with siblings.

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

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

Schema covers 100% of parameters with descriptions; description adds example keys and value types, enhancing understanding for the agent.

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

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

Clearly states the tool saves data for reuse later, with examples of what to save. Distinguishes from sibling tools recall and forget by naming them.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and mentions pairing with recall and forget, providing clear context for when to use.

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

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

Annotations already declare read-only and idempotent hints, but the description adds substantial behavioral context: it labels each identifier with its source, explicitly includes unresolved identifiers under an `unresolved` field, gracefully degrades if GLEIF/OpenFIGI are unavailable, and cascades through multiple endpoints internally. This goes well beyond the annotations and clarifies failure modes.

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

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

The description is long but dense and well-structured, starting with usage examples and front-loading the core purpose. Every sentence adds value, covering types, behaviors, and fallbacks. It could be slightly more concise, but the detail is essential for an agent to understand the tool's capabilities and limitations.

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

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

Given no output schema and the complexity of two entity types with multiple identifiers, the description is highly complete. It explains what identifiers are returned (CIK, LEI, FIGI, RxCUI), how sources are labeled, how unresolved IDs are handled, and how enrichment failures degrade gracefully. This covers the key operational aspects an agent needs.

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 enriches parameter meaning significantly. For 'company', it lists accepted inputs (ticker, CIK, ISIN, or name) and explains the resolution logic (e.g., ISIN maps to the legal entity via GLEIF). For 'drug', it specifies RxCUI, ingredient, brand, and citation behavior. This exceeds 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 explicitly states the tool resolves user-spoken names to canonical/official identifiers needed by other tools, with concrete examples of query phrasings. It clearly differentiates itself by emphasizing the cross-source identity spine (CIK, LEI, FIGI) and the 'resolve to ID' use case, which is distinct from sibling tools like resolve_term.

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 strong when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly mention when not to use it or name alternative tools for other scenarios, though the 'first' directive is quite clear.

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

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

The description adds valuable behavioral details beyond annotations, such as the two-step matching strategy (exact then fuzzy) and the fact that it is keyless, without contradicting the read-only and idempotent hints.

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

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

The description is extremely concise, with two sentences: the first defines the purpose and the second explains the matching algorithm. 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?

The description covers the core behavior and usage, but lacks details on the return format (no output schema). However, given the simple mapping function and existing schema/annotations, it is mostly 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 schema already covers both parameters with descriptions, but the description adds algorithmic context (exact then fuzzy fallback) that enhances understanding, though not necessary for 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 the tool maps free-text terms to canonical MeSH descriptors, distinguishing it from siblings like resolve_entity and get_descriptor by specifying the resource and verb.

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

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

The description explains when to use the tool (mapping synonyms to PubMed headings) and its matching behavior, but does not explicitly mention when not to use it or contrast with alternatives like search_descriptors.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that the tool internally calls ai_visibility_check, ranks results, and returns a list with score, confidence, and signal density per entity. This behavioral context goes beyond annotations 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?

Three sentences: first states purpose, second explains mechanism and output, third gives a use case. No filler, front-loaded with the core action. 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 4 parameters, no output schema, and good annotations, the description covers what the tool does, how it works, and what it returns (ranked list with score/confidence/signal density). It could explicitly mention the 2-8 entity requirement, but that is in the schema. Overall, complete for a comparison 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%, but the description adds semantic value: clarifying that the first entity is treated as the 'subject' for narrative, explaining 'workers-ai' as the free default for models, and providing an example for context. This extra guidance helps the agent understand parameter roles 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 compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. This is a specific verb and resource, distinct from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a concrete use case (competitive AI-marketing audits) and implicitly contrasts with ai_visibility_check by mentioning it as the underlying probe. However, it does not explicitly state when not to use this tool or list alternative tools for single-entity checks.

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

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

Adds significant context beyond annotations: composite call behavior, partial failure handling, timing details (bundlephobia first measurement 5-30s), and return fields. Annotations already indicate readOnly, idempotent, non-destructive; description reinforces and elaborates.

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

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

Description is longer but highly informative, front-loaded with purpose. Every sentence adds value, though could be slightly more structured for quick scanning.

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 details return fields (summary block, per-advisory, links, alternative versions) and partial failure behavior. This is comprehensive for a composite tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description adds useful context: scoped packages accepted, version defaults to latest. This adds value beyond schema, justifying a score above baseline 3.

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

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

The description clearly states it's a composite check for npm packages, fanning out across deps.dev and bundlephobia. It provides a specific verb ('scan') and resource ('dependency'), and distinguishes itself from sibling tools by focusing on npm package evaluation.

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

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

Explicitly states when to use: when an agent asks about safety, popularity, or size of an npm package. Provides clear guidance on NPM-only limitation and directs other ecosystems to deps.dev:version directly.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by clarifying the input domain (disease/drug/concept), return format (descriptor IDs), and that no API key is needed (Keyless). 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 two sentences long, front-loads the core purpose, includes examples, and states key attributes (returns, Keyless). No redundant or unnecessary words.

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

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

Given the tool's simplicity (3 parameters, no output schema, strong annotations), the description fully covers what an agent needs: input semantics, output type, authentication status, and use case examples. No gaps remain.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The tool description adds little new semantic information beyond the schema, only providing example terms ('diabetes', 'aspirin'). Thus, a 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: 'Search NLM MeSH descriptors by a disease/drug/concept term' and specifies the return type 'MeSH descriptor IDs (Dxxxxxxx)'. It distinguishes itself from siblings like 'get_descriptor' by calling itself 'The core free-text-to-MeSH lookup' and notes it's 'Keyless', adding unique context.

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 this is the primary tool for searching MeSH by free text, and mentions 'Keyless' as a usage condition. However, it does not explicitly state when to avoid this tool or name alternatives, leaving some ambiguity for an agent.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds significant behavioral context: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity metric (cosine), character limit (200K chars with truncation flag). This goes well beyond annotations and is fully consistent.

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

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

The description is three sentences, each serving a distinct purpose: purpose, usage guidelines, and technical details. It is front-loaded and contains no redundant or unnecessary words.

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

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

Despite no output schema, the description fully explains the return value (passages with character offsets and similarity scores), covers technical constraints (max 200K chars, truncation flag), and integrates well with sibling tools. It is 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 coverage is 100% with descriptions for all 3 parameters. The description adds minimal extra semantics: it clarifies that 'text' is the fetched record and encourages natural-language examples for 'query'. This is baseline 3 as per guidelines.

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 ('semantic search') and resource ('inside a fetched record'), providing concrete examples like SEC 10-K body and long tool results. It also distinguishes itself from siblings by mentioning its 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?

The description explicitly states when to use ('record too big to cram into the prompt') and explains the benefit (saves context, returns relevant passages with offsets). It also suggests a complementary tool (ask_pipeworx_grounded). While it doesn't explicitly say when not to use, the guidance is clear and sufficient.

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

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

The description adds significant behavioral context beyond annotations: it discloses that the tool returns a new subscription ID, details delivery channel behaviors (autodisabling webhooks after 10 failures), OAuth requirement, and phone verification needed for SMS. 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 informative, with clear sentences separating purpose, types, and delivery details. It could be slightly more concise but remains effective.

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

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

Given the complexity of multiple subscription types, nested parameters, and delivery channels, the description is complete. It covers required steps (phone verification, OAuth) and return value (subscription ID), and no output schema is needed as the description suffices.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by explaining each subscription type's parameters with concrete examples (e.g., sec_8k items codes, fred_series series_id) and delivery constraints, which the schema alone does not fully convey.

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 a live-data event stream. It lists supported types with examples, distinguishing it from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 context on when to use the tool, including requirements (Pipeworx OAuth account) and delivery channel limitations (SMS cap, phone verification). It implies alternatives like recent_alerts for pulling the feed, though it does not 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?

Annotations already declare read-only, idempotent, etc. Description adds value by detailing that it returns category-bucketed example questions with exact tool and argument shapes. No contradiction with annotations.

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

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

Description is somewhat long but well-structured with examples and explicit usage. Every sentence adds value. Minor improvement could be slightly tighter wording, but overall effective.

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

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

Given no output schema, the description thoroughly explains what is returned (category-bucketed example questions with tool shapes). Covers parameter, use case, and output format. Complete for this tool's 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 description coverage is 100%, so baseline is 3. Description adds extra context: lists possible topic values (finance, pharma, etc.) and explains that omitting topic gives a cross-category spread. This goes beyond the schema's minimal 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?

Description clearly states the tool is the onboarding entry point for getting example questions about Pipeworx. It specifies the verb 'suggest' and resource 'questions', and distinguishes from siblings like 'ask_pipeworx' by focusing on showing what one can ask.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Provides clear context for when to use, but does not explicitly exclude or compare with all sibling tools.

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

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

The description adds value beyond annotations by explaining that the row is deactivated rather than deleted, preserving historical events. This reinforces the idempotentHint=true and destructiveHint=false annotations with specific behavioral details.

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

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

The description consists of three concise sentences, front-loading the action and key constraint, with no extraneous information. Every sentence adds essential context.

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 no output schema, the description covers purpose, ownership, side effects, and data retention behavior comprehensively. Annotations provide additional safety context, making the definition 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% for the single 'id' parameter, which already includes a clear description. The tool description does not add additional parameter-level details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id,' providing a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions by adding ownership enforcement and deactivation vs deletion behavior.

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 ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for when to use the tool. It does not explicitly list alternatives or exclusions, but the ownership constraint guides appropriate usage.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description goes further by disclosing critical behavioral nuances: the meaning of could_not_verify (check did not happen, not evidence) and its distinction from unsupported, plus the inclusion of verification_error{stage,detail}. This contextualizes the verdict types and prevents misuse.

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 opens with trigger phrases for rapid identification, then logically proceeds through purpose, pathways, return value, and critical caller caveats. Every sentence contributes essential information—no filler. Despite its length, it's tightly structured with clear segmentation (including an 'IMPORTANT for callers' emphasis), maximizing scannability.

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

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

With no output schema, the description fully carries the burden of explaining return values: it lists the verdict types, mentions the grounded/structured actual value with citation, and specifies the reasoning component. It also covers error handling (could_not_verify vs. unsupported) and the tool's efficiency advantage, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds significant semantic value: claim is illustrated with two concrete examples, and tolerance_pct is explained with its purpose (hallucination detection), range (0.5–50), override behavior, and default cap. This goes well beyond the schema's basic parameter descriptions.

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

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

The description explicitly identifies the tool as natural-language claim verification against authoritative sources, with a clear verb ('validate') and resource (claims). It distinguishes itself from sibling tools by describing its specific routing logic (SEC EDGAR fast path vs. grounded pipeline) and noting it replaces 4–6 sequential calls, making its unique 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 states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing a direct usage condition. It also explains the two distinct paths (company-financial claims vs. any other factual claim), guiding selection based on claim type, and implies alternatives by noting it replaces multi-step sequential calls.

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