Usgs Water

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

Annotations already indicate safe read-only, idempotent behavior. The description adds context about external API calls to Anthropic (if key provided) and the return format per model, but does not detail rate limits or other limitations. This adds value beyond annotations.

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

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

Single paragraph of three sentences, no redundancy. Front-loaded with purpose, then details on models and return. Every sentence is informative and earns its place.

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

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

Despite no output schema, the description explains the return format (per-model fields + combined view) and scoring range. Inputs are fully described. The tool's behavior is complete for its complexity.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds context about default model and when to use _apiKey, which augments the schema. No param is left undocumented.

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

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

The description clearly states the tool probes LLMs to score visibility of a business/brand/product/topic, with specific verb 'probe' and resource 'LLMs'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on generic brand visibility scoring rather than competitor-specific analysis.

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 checks, competitive monitoring) and explains when to provide an API key for Anthropic. However, it does not explicitly state when not to use it or compare to alternatives like 'scan_competitor_ai_presence'.

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

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

Annotations already cover read-only, open-world, idempotent, non-destructive behavior. The description adds useful behavioral context: it routes/fills arguments and returns a structured answer with stable pipeworx:// citation URIs. No contradiction with annotations, but no extra detail on latency or 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 its most important directive and is information-dense, but it is somewhat repetitious ('even if web search could also answer it' and 'START HERE for most questions' restate earlier guidance). It ends with a stray ellipsis that suggests truncated content, which hurts structure.

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

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

For a single-parameter tool with rich annotations, the description covers the core information an agent needs: when to use it, what data domains it supports, example questions, and the citation-bearing response shape. The lack of explicit guidance about sibling variants and edge cases is a minor gap.

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

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

Schema coverage is 100% and the parameter is self-explanatory, so the baseline is 3. The description adds value with a breadth of example questions and trigger language ('what is', 'look up', 'current'), helping an agent formulate the single required question 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 clearly identifies the tool as a factual question router: 'Routes the question to the right one of 5,798 tools across 1517 verified sources' and says it returns structured answers with citation URIs. It is specific about domains and trigger phrases, but it does not explicitly distinguish ask_pipeworx from sibling variants like ask_pipeworx_beta and 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?

Extremely explicit about when to prefer it: 'PREFER OVER WEB SEARCH' for factual/current/historical data, with trigger phrases and concrete examples, and 'START HERE for most questions.' It offers no explicit when-not-to-use guidance or alternatives beyond web search, so it stops short of a 5.

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

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

The description goes well beyond the annotations by disclosing live candidate routing tests, the current no-candidate state with a retirement date, exact behavioral match to the stable router, and the fact that this is a full working router rather than a degraded fallback. This is consistent with the readOnlyHint, idempotentHint, and non-destructive annotations, so there is 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?

The description is front-loaded with the definition and current status, and nearly every sentence adds useful behavioral or usage context. There is minor redundancy between 'identical universal router' and 'currently matches ask_pipeworx exactly,' but the overall length is justified by the operational detail.

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

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

For a single-question routing tool with rich annotations, the description covers current behavior, experimental purpose, and usage guidance well. It relies on ask_pipeworx for response-shape details rather than explaining the response format itself, which is acceptable but leaves a small gap if the agent does not already know the stable sibling.

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

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

Schema description coverage is 100%, with all six parameters described, including the question field and its aliases. The tool description adds no additional parameter-level semantics, so the baseline score of 3 is appropriate; it correctly avoids repeating what the schema already documents.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,798 tools, arguments, and response shape. It explicitly frames itself as the experimental edge, which distinguishes it from the stable sibling ask_pipeworx without needing to open either schema.

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

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

It gives a direct usage instruction: use it exactly like ask_pipeworx when you want the newest routing. It names the stable alternative and explains that results are compared against the stable router for merge decisions, though it does not explicitly say 'use the stable version when you want to avoid experimental behavior.'

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 carry readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral detail: the exact success/refusal JSON shapes, the complete list of refusal_reason enums, and the cost implication of one extra LLM call. It also clarifies that it uses only the tool result content, which is a safety-relevant 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 dense but every sentence earns its place: it states the core distinction, gives the return/refusal contract, supplies usage conditions, and provides a cost tradeoff. It is front-loaded with the most important qualifier ('Hallucination-resistant answer mode') and avoids redundant filler.

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

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

There is no output schema, so the description must and does explain the return values, including both success and refusal shapes and the meaning of refusal reasons. It also covers when to use, when not to use, and the cost delta. Nothing essential for calling this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents the 'question' parameter and its aliases. The description does not add parameter-specific detail beyond implying that the question drives tool routing and argument filling, which is expected. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly identifies a specific verb+resource: this is a 'grounded' answer mode that extracts answers only from tool results, with explicit refusal behavior. It differentiates itself from the sibling ask_pipeworx by emphasizing the extraction constraint and the refusal reasons.

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 when-to-use guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete examples (financial verdicts, legal claims, medical lookups). It also names the alternative (ask_pipeworx) and states when to prefer it ('for casual lookups'), plus notes the extra LLM call cost.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: response shapes, resolver contract, parent event extractor, news fields, safety (low-confidence, closed markets), wide spreads, resolution-rule risk. Adds significant value beyond annotations; 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 detailed but verbose (multiple paragraphs). Front-loaded with purpose, then extensive details. Every sentence adds value, but could be more concise. Structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.)

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, so description must cover return values. It thoroughly explains response shapes, resolver contract, parent event, news fields, safety, etc. Given complexity, it is complete.

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

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

Schema coverage is 100%; description adds context like examples, depth explanation, include_raw behavior. Baseline 3, description adds marginal value, so 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?

Description explicitly states the tool researches Polymarket bets by pulling PipeWorx data, resolving markets, classifying, and fanning out. It distinguishes from siblings like polymarket_edges by focusing on single-bet research. Verb+resource: 'Research a Polymarket 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?

Clearly states when to use: 'should I bet on X', 'what does the data say about Y'. Provides examples of classification and fan-out. Lacks explicit when-not or alternatives, but context is strong.

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 document readOnlyHint=true and other hints. Description adds useful behavioral details such as data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorted results. Does not contradict annotations.

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

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

Description is relatively long but each sentence adds value, front-loaded with example phrases. Could be slightly more concise, but no wasted sentences.

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

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

No output schema, but description mentions return format (paired data + citation URIs). Given the complexity of comparing 2-5 entities with two types, the description provides sufficient completeness for an agent to understand what the tool does and returns.

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%, baseline 3. Description adds value by explaining the enum choices for type parameter (what data each pulls) and clarifying values parameter (tickers vs drug names, min/max items).

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 performs side-by-side comparison of 2-5 companies or drugs in one parallel call, with specific verb 'compare' and resource 'entities'. It distinguishes from siblings by noting it replaces 8-15 sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. Does not explicitly state when not to use, but implies single-entity lookups are for other tools like entity_profile.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying 'Keyless' (no authentication needed) and confirming the return of 'most recent value per site × parameter', which aligns with annotations without contradiction.

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

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

The description is four sentences, each serving a purpose: stating purpose, return format, common codes, and access method. No unnecessary information.

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

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

The tool has no output schema, but the description clarifies the return structure (most recent value per site × parameter). For a simple read tool, this is sufficient, though a brief note on response format would be slightly more 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%, but the description enhances understanding by listing common parameter codes with units and examples, providing context beyond the schema's basic descriptions.

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

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

The description clearly states it returns 'latest instantaneous (real-time) readings' for USGS gauge sites, specifying the resource and action. It distinguishes from a sibling tool like 'daily_values' by focusing on real-time data.

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

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

The description implies usage for real-time data but does not explicitly state when to use this tool versus alternatives like 'daily_values' or 'find_sites'. There is no 'when not to use' guidance, only implied context.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. Description adds that the tool is 'Keyless' (no auth) and returns 'one statistic per day', which aligns with annotations. No contradictions. Could mention rate limits or pagination, but the tool is simple and annotations cover safety.

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

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

Three sentences, front-loaded with the core action ('Daily-values time series...'), followed by usage guidance and common codes. Every sentence adds unique value, no redundancy.

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

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

Despite no output schema, the description specifies the output ('one statistic per day') and gives examples of what parameters mean. Parameters are well-documented. For a straightforward read-only data retrieval tool, this is comprehensive enough for correct 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 provides full coverage (100%) with descriptions for all 5 parameters. Description adds significant value by listing common stat codes (00001, 00002, 00003) and parameter codes (00060, 00010, 00065) with their meanings, which are not in the schema. This helps the agent select correct parameter values.

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 verb ('returns'), resource ('daily-values time series for a single USGS site + parameter'), and scope ('over a date range, one statistic per day'). Distinguishes from sibling tools by specifying a unique data type (daily historical time series) not offered by other tools like 'current_conditions' or 'recent_changes'.

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 usefulness for 'trends, hydrographs, and historical comparison' and provides common parameter and stat codes. Lacks explicit when-not-to-use or alternative tool mentions, but the sibling list includes relevant alternatives like 'current_conditions' and 'recent_changes', which are implied as non-daily or non-historical.

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 annotations, the description discloses return-packet fields (evidence, confidence, source, fetched_at, citation_uri), gap reporting, contradictions scan, no-invention behavior, semantic excerpting, and latency expectations. This is unusually transparent for a tool without an output schema.

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 the tool is complex and lacks an output schema, so most sentences earn their place. It is front-loaded with the account restriction and fallback tool, though the prose could be tightened with bullet separation or pruning of repeated depth details.

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

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

For a complex, output-schema-less, multi-mode research tool, the description covers prerequisites, alternatives, selection guidance, input behavior, output structure, timing, and limitations (gaps and fetchable citations only when source emits them). No critical operational context is missing.

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

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

Schema description coverage is 100%, so the schema already documents question and depth semantics, including hop/count/paid details. The description adds operational color such as latency and hop behavior, but most parameter meaning is already present in the structured schema, so the 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 identifies a specific action ('research') with a specific resource (1517 structured data sources) and a distinct process (decomposing questions, parallel routing to tools, findings packet). It explicitly differentiates itself from open-web search and sibling ask_pipeworx, so an agent can recognize when this is the right tool.

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

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

Explicit usage context is given: best for broad/multi-part structured-data questions, while a single lookup should use ask_pipeworx. It also states the auth prerequisite and directs unsigned-in users to ask_pipeworx as the fallback, which is actionable routing guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail: returns top-N tools with full schemas and curated examples, ready to call directly. 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?

Front-loaded purpose, efficient enumeration of use cases, and clear call-to-action. Every sentence adds value; no fluff.

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

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

For a tool with 6 parameters and no output schema, the description thoroughly explains what the tool returns and how to use it. It covers inputs and outputs adequately.

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%, baseline 3. The description elevates by providing natural language examples and clarifying that multiple aliases exist. It adds context beyond schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific data domains and tasks, distinguishing it from sibling tools that perform actions rather than discovery.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly tells the agent when to use this tool before others.

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

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

The annotations already mark readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering safety and nondeterminism. The description then adds behavioral context beyond those annotations: parallel fan-out, soft-fail behavior, resolved_from/resolved_to, empty-section semantics, and the resolved:false notes line for private companies. That is rich transparency that annotations alone cannot provide.

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

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

The description is long and dense, but nearly every clause adds needed context: input alternatives, output composition, fallback behavior, failure semantics. It front-loads the trigger phrases, scope, and parallel-call advantage. It sacrifices brevity for completeness, which is justified here, though a future editor could trim some repetitive examples.

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

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

With only two simple parameters, no output schema, and complex fan-out behavior, the description is remarkably complete. It explains what data comes back, what empty sections mean, how failures are reported, acceptable input formats, and when not to use it. An agent can reliably decide to call it and interpret results correctly from this description alone.

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 value above the schema by explaining that `type` and `value` are interchangeable, that names resolve via SEC EDGAR, and that value accepts either ticker, CIK, or company name. The one gap is not explaining what 'company' vs 'ticker' semantically maps to in results, but since both behave identically, the description sufficiently handles it.

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

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

The description opens with many concrete trigger phrases and a crisp summary: 'full cross-source profile of a US public company in ONE parallel call.' It names the exact resources (SEC EDGAR, XBRL, USPTO, USAspending, FDA Purple Book, DOL LCA, news, GLEIF) and outputs. This distinguishes it from siblings like compare_entities or resolve_entity because the scope is definitively a single-entity holistic company profile.

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

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

It explicitly instructs agents to ALWAYS PREFER this tool over chaining single-pack SEC/XBRL/news lookups for holistic user requests. It also explains when failures are expected (private company, FDA small-molecule absence, USPTO soft-fail) and gives accepted input shapes, which is strong usage guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: the tool is 'Keyless' (no API key required) and 'results are capped' (limit handling). 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?

Two sentences, no wasted words. The first sentence covers the main action and context; the second adds key operational detail (capping). Ideal length for this simple tool.

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

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

For a simple query tool with 3 parameters and no output schema, the description is mostly complete: it explains the return ('sites with latest reading'), mentions capping, and notes keyless access. It could be slightly more specific about output fields (e.g., site name, ID, value), but is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema already provides; for example, the default for parameter_code is already in the schema description.

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

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

The description clearly states the tool discovers active USGS gauge sites in a US state reporting a given parameter, using specific verbs ('Discover', 'Returns') and naming the resource. It distinguishes from siblings like 'current_conditions' or 'daily_values' by focusing on site discovery, but does not explicitly differentiate.

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

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

The description implies usage for finding live gauges in a region and notes that results are capped due to many matches. However, it does not provide explicit guidance on when not to use this tool versus available siblings (e.g., 'current_conditions' for specific site data), nor does it mention 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 destructiveHint=true and idempotentHint=true. The description adds that it deletes a memory, which is consistent. No additional behavioral details beyond the annotations are provided.

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

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

Two concise sentences that are front-loaded with the action and purpose. No extraneous information; 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?

For a simple tool with one parameter, full schema coverage, and informative annotations, the description provides sufficient context: purpose, usage, and related tools. No output schema is needed.

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

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

Schema coverage is 100%, with the 'key' parameter fully defined. The description mentions 'by key' but adds no new semantic information beyond what the schema already provides.

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

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

The description explicitly uses the verb 'Delete' and specifies the resource 'previously stored memory by key'. It clearly distinguishes from sibling tools 'remember' and 'recall' by naming them and implying different actions.

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

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

Description provides explicit contexts: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with related tools. However, it lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond the 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?

The description is concise and well-structured: it states the purpose upfront, explains the process, and lists use cases. Every sentence adds value with no 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 no output schema, the description fully explains the output format (single text blob ready for site root) and covers the process and use cases. For a two-parameter tool, this is complete and sufficient for an agent to understand what the tool does and what to expect.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'url' implicitly via 'Fetches the page' and 'max_links' via 'Maximum number of link entries', but does not add new semantic details or examples beyond what the schema already provides.

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

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

The description clearly states the tool generates a production-ready llms.txt file for a given URL, specifying the format and output. It uses a specific verb ('generate') and resource ('llms.txt file'), and the context of indexing by AI crawlers differentiates it from sibling tools like scan_competitor_ai_presence.

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

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

The description lists concrete use cases (indexing a client's site, drafting for own project, auditing competitors) but does not explicitly state when not to use the tool or provide direct alternatives. The guidance is clear but lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds return field list (id, type, params, etc.), which supplements behavioral understanding beyond annotations.

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

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

Two sentences, front-loaded with purpose, followed by usage guidance. No unnecessary words.

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

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

Given low complexity (1 optional boolean, no output schema), description covers return fields and usage context completely.

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

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

Schema description coverage is 100% with clear parameter description. Tool description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'list' and resource 'subscriptions', and specifies scope as 'caller's active'. It distinguishes from siblings like 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?

Provides clear context: use to review monitoring before adding more or to find an id to cancel. Explicitly tied to sibling actions. Lacks explicit when-not-to-use, but 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 are all false, providing minimal safety signals, so the description fully bears the transparency burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later... to read whether it was fixed'), and that it is 'Free; doesn't count against your tool-call quota.' These are meaningful behavioral traits beyond the annotations.

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

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

Though long, every sentence earns its place: purpose, usage triggers, exclusion for non-Pipeworx tools, claim_token mechanics, rate limit, digest frequency, cost. It is front-loaded with the core purpose and structured logically, avoiding 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?

The tool has dual modes (filing feedback and checking a prior filing via claim_token), no output schema, and a complex input schema with nested context. The description explains both modes, rate limits, scope, and what to include, making it fully self-contained for an agent to invoke 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, but the description adds substantial operational detail: it instructs how to frame the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and gives an exact usage pattern for claim_token ('pipeworx_feedback({claim_token:"pwfb_…"})'). This goes beyond the schema's field-level 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 opens with a clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates use cases (bug, feature, data_gap, praise), making it distinct from sibling tools like ask_pipeworx or discover_tools, which are for querying or 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?

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: only for tools served by this Pipeworx connection, and directs users to file with other MCP servers instead, which is an explicit alternative.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: it explains the data source ('CF analytics-engine'), that no PII is included, the aggregation format (pack, tool, count), and caching duration. 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 tightly written with two paragraphs, front-loaded with the core action. Bullet points for use cases improve readability. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description specifies the return contents (top tools, top packs, total call volume). It covers caching, data source, and privacy. For a simple trending tool, this is complete and leaves no major gaps.

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

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

Schema description coverage is 100% with a detailed enum description already explaining window trade-offs. The tool description restates this but does not add new parameter-level details beyond the schema. Baseline 3 is appropriate as the schema carries the burden.

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

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

The description clearly states that the tool returns top tools, top packs, and total call volume over a configurable time window. It uses a specific verb 'Returns' and specifies the resource, distinguishing it from sibling tools focused on asking questions or accessing data.

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

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

The description explicitly lists three use cases: discovering hot data sources, confirming canonical tool choice, and aligning use cases with agent demand. It also explains the trade-offs between windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), providing clear guidance on when to use each option.

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) already indicate safe, non-destructive behavior. The description adds extensive behavioral context: algorithms (monotonicity, partition-sum), fill check against CLOB depth, semantic anchor for cross-event, partition filter, and response structure. 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 lengthy but well-organized with capitalized key terms. Every sentence adds value, though a more structured format (e.g., bullet points) could improve readability. The front-loaded sentence immediately conveys purpose and modes, but the density may challenge agents. Appropriate for complexity.

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

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

Despite no output schema, the description explains the response structure (opportunities[] with fields, partition_check in event mode) and the fill check logic. It covers all modes, parameter usage, behavioral nuances, and references a sibling tool for custom sizing. Complete for a complex arbitrage detection 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 significant meaning: explains the distinction between event and topic modes, provides example slugs/seed questions, describes what happens in each mode (walks child markets, date-axis/threshold-axis ordering, partition_check). This goes well beyond the schema's parameter descriptions.

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

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

The description clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes three modes (no-args trending scan, event mode, topic mode) with explicit examples. It avoids tautology and effectively differentiates from sibling tools by referencing polymarket_fill_risk.

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

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

The description provides explicit guidance: 'Call with NO args for a `trending_scan`... `event` (recommended for a specific market)... `topic` (for cross-event scanning).' It explains when to use each mode, the fill check condition (do not trade if realizable_edge_pp <= 0), and points to polymarket_fill_risk for custom sizing, offering clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false. The description goes far beyond these by detailing caching (1h KV level), edge calculation with slippage, Kelly caps, tradeable-edge filters, diagnostic fields, and the Fed note. This provides exceptional transparency about the tool's 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 very long (approximately 400 words) and information-dense. While it is front-loaded with the purpose, it dives deep into technical model details and operational notes. Some sections could be condensed or better structured to improve readability without losing critical information.

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

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

Given the tool's complexity (9 parameters, no output schema, nested concepts like segments and diagnostics), the description is highly complete. It covers all aspects: model families, response structure, tradeable-edge filters, caching, and even context for Fed bets. No obvious gaps remain for an agent to understand its use.

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 descriptive names and explanations for all 9 parameters. The description adds significant value by explaining the context and reasoning behind each knob, such as how min_partition_leg_kelly applies to per-leg Kelly in partitions, and how max_spread_pp and min_liquidity act as tradeable-edge filters. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes itself from sibling tools by specifying its use case ('what should I bet on today') and detailing three distinct model segments, making it clear what the tool does and how it differs.

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

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

The description explicitly says it's built for agents to discover opportunities without paging through hundreds of markets, providing clear context for when to use it. However, it does not explicitly state when not to use it or mention specific alternatives, though the sibling list implies differentiation.

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 the annotations. It explains that the tool reads snapshots, computes decay, and returns tracked, expired opportunities, and snapshot dates. It also clarifies the signed nature of edge_pp_net and the limitations of decay computation. No contradiction with annotations.

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

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

The description is well-structured with clear sections: core question, arguments, response breakdown, limits. It front-loads the purpose and uses readable formatting. Some minor redundancy, but overall concise enough for the complexity.

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

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

Given the absence of an output schema, the description fully compensates by detailing the response structure (tracked, expired, snapshot_dates) and their fields. It also covers edge cases like gaps in snapshots and limitations, making it highly complete.

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

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

Schema coverage is 100%, but the description adds value by explaining default and clamp behavior for 'days' (default 14, max 30) and the default for 'window' (1wk). It also clarifies the snapshot family concept, which the schema's description only labels as 'window family'.

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

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

The description clearly states the tool's purpose: answering how long an edge has existed and whether it is shrinking. It distinguishes itself from sibling tools like polymarket_edges by focusing on persistence and decay telemetry, not just current edge values.

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

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

The description implicitly guides usage by focusing on edge persistence analysis, and mentions limitations such as the 60-day TTL and daily closes. While it doesn't explicitly state when not to use it, the context of siblings and the detailed output structure provide clear usage context.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false. The description adds rich behavioral context: walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about thin legs and forced directional risk. No contradiction with annotations.

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

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

The description is somewhat lengthy but well-structured with clear sections (SINGLE-MARKET, BASKET) and bolded key terms. Every sentence adds value, but minor redundancy could be trimmed without losing clarity.

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

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

Given the tool's complexity (two modes, rich return fields, risk implications) and the absence of an output schema, the description is remarkably complete. It details all key outputs for both modes, covers edge cases (thin_legs, forced_directional_risk), and provides usage thresholds. 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%, but the description adds substantial meaning beyond schema: explains the requirement for either market or event, differentiates parameter roles in single-market vs basket modes, and clarifies size_usd interpretation (spend vs target proceeds vs settlement notional). This goes far beyond the schema descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two distinct modes (single-market and basket) with specific verbs and resources. This differentiates it well from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why not to skip it, citing the risk of uncapturable theoretical overround on thin books and partial basket fills converting arb into directional risk.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description goes far beyond them: it discloses compatibility warning behavior, machine-readable codes, fee treatment (gross not net), skipped comparisons, matching methodology, temporal alignment pitfalls, and the meaning of null. This is exceptionally transparent for a tool with no output schema.

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 the tool is genuinely complex and there is no output schema to shift detail into. It is front-loaded with purpose, modes, response shape, then safety and caveats. Some phrasing is repetitive, such as re-emphasizing that compatibility fields must be read, but every major sentence contributes operational value.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: response fields, spread output, compatibility codes, per-entry flags, skipped/unknown handling, temporal alignment, fees, and caveats. An agent can understand not just how to call it but how to interpret ambiguous or incomplete 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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: the relationship between topic and explicit parameters, that both modes run the identical matcher, that explicit parameters override the mapped side, and that the same disclosures apply to both. This goes beyond what the schema alone provides.

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

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

The description clearly identifies the tool as computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from related Polymarket siblings by explicitly naming both venues and the 'same resolving question' scope, so an agent can select it confidently without needing to inspect sibling schemas.

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

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

The description gives explicit usage context: two modes, a list of pre-mapped topics, and explicit ticker/slug pairing. It also warns that pre-mapped topics often return compatibility warnings and are not necessarily tradeable. However, it does not explicitly mention when to prefer an alternative sibling tool or state exclusions, so it stops short of full alternative routing guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds scope (scoped to identifier) and the dual behavior (list all vs single retrieve). It does not contradict annotations and adds useful context.

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

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

Three sentences front-loaded with action. Every sentence adds value: what it does, when to use, scope and pairing with siblings. No wasted words.

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

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

For a simple tool with 1 optional param and no output schema, the description fully explains both modes, scope, and pairing. Complete and self-contained.

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

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

Schema has 1 parameter (key) with 100% description coverage. The description adds meaning by explaining the optional nature: 'omit the key argument to list all keys.' This clarifies usage 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 (retrieve/list), the resource (saved memory), and distinguishes from siblings (remember/forget). It explicitly says 'Retrieve a value previously saved via remember, or list all saved keys' and provides concrete examples.

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

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

The description explains when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also implies when not to use by mentioning pair tools remember/forget for save/delete. It could be more explicit about 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 indicate read-only, idempotent, and non-destructive behavior. The description adds value by explaining that setting mark_read:true flags events as read for subsequent calls and that polling is supported, enhancing transparency.

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

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

The description is concise (4 sentences) and front-loaded with purpose. Every sentence adds information, though it could be structured as bullet points for clarity. No wasted words.

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

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

Given no output schema, the description explains return fields (source, citation_uri, payload) and key behaviors (filtering, mark_read, polling). It does not cover pagination or error handling, but is fairly complete for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning for 'type' (e.g., 'sec_8k'), 'since' (ISO timestamp), and 'mark_read' (effects on future calls), going beyond the schema. It does not describe 'limit' or 'unread_only', but overall adds 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 uses a specific verb ('Pull') and resource ('fired events from your subscription feed'). It clearly explains what the tool does and distinguishes it from siblings by focusing on recent alerts with specific fields.

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 guidance on filtering by type and since, and notes that polling works fine. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, leaving some ambiguity.

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

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

Discloses fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), mentions failure modes (PatentsView API sunset soft-fail). Annotations already mark readOnly, idempotent, non-destructive; description adds valuable context.

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

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

Front-loaded with example queries, dense but each sentence adds value. Slightly long but justified given complexity.

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

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

No output schema, but description mentions return structure (changes[], total_changes, citation URIs). Covers use cases and limitations adequately.

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

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

Schema covers all parameters (100% coverage). Description adds helpful examples like '30d' and zero-padded CIK, but baseline already high.

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

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

The description clearly states it provides a change feed for a company in a time window. It gives multiple example queries and distinguishes from sibling tool entity_profile for static profiles.

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

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

Explicitly says when to use (for dynamic changes) and when not to (use entity_profile for static profile). Includes example queries and typical since values.

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

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

Adds context beyond annotations: describes key-value storage, scoping by identifier, and persistence differences between authenticated and anonymous users. 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?

Five sentences, each serving a distinct purpose: purpose, usage, scope, persistence, pairings. No wasted words, well-structured.

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

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

For a simple 2-param tool with no output schema, the description covers all needed aspects: function, usage, behavior, and companion tools, making it fully complete.

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

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

Schema has 100% coverage with clear descriptions for key and value. The description adds useful context about memory scope and persistence, enhancing understanding beyond the schema.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, uses specific verb 'save' and resource 'data' as key-value pairs, and distinguishes from siblings by mentioning recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides alternatives: 'Pair with recall to retrieve later, forget to delete.' Also clarifies scope and persistence.

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

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

Annotations already mark it read-only and idempotent. The description adds substantial behavioral context beyond that: it cascades through multiple endpoints, degrades gracefully when GLEIF/OpenFIGI are down, labels identifiers by source, explicitly reports unresolvable IDs under 'unresolved', and does not assert ambiguous matches. Contradicts nothing.

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 detailed, arguably too verbose. It front-loads examples and purpose, but then dives into extensive source-attribute details (SEC EDGAR, GLEIF, OpenFIGI) that could be condensed. Every sentence adds some value, but the density might overwhelm an agent. A tighter version would score higher.

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 resolver with no output schema, the description covers return behavior (figi_candidates, unresolved list), gracefully falling back, and even the internal cascade. It explains what to expect when input is ambiguous. An agent has everything needed 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?

Schema covers both parameters at 100%, but the description adds critical nuance: for 'type' it clarifies the enum semantics; for 'value' it provides examples, warns against full noun phrases, and explains FIGI matching behavior. This is significant added meaning beyond the schema.

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

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

The description opens with concrete user queries and states the core purpose: resolving a spoken name to canonical identifiers. It explicitly lists the supported types (company, drug) and the identifier outputs (CIK, LEI, FIGI, RxCUI), distinguishing it from sibling tools that consume those IDs. 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?

It gives explicit positive guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains when a name is ambiguous (asserts nothing and returns figi_candidates). However, it does not explicitly name alternatives or state when NOT to use it (e.g., when you already have an ID and want details, use entity_profile). Still clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe, read-only behavior. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, signal density. This provides helpful behavioral context beyond the annotations without contradiction.

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

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

Three sentences: first states action and result, second explains process and use case, third describes output. No redundancy, front-loaded, every sentence earns its place. Very concise for a tool with 4 parameters.

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 (1 required) and no output schema, the description adequately explains the output structure. It also mentions conditions for using _apiKey. Could be slightly more detailed on output format or error scenarios, but it's sufficiently complete for an analysis 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%, so the bar is lower. The description adds meaning beyond schema by explaining that the first entity in the 'entities' array is treated as the 'subject' for narrative and that 'models' defaults to workers-ai. These nuances help the agent use parameters correctly.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, ranking them. It distinguishes from the sibling tool 'ai_visibility_check' which is for a single entity. The verb 'compare' and resource 'AI visibility across entities' are specific.

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

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

The description gives a concrete use case ('competitive AI-marketing audits') and explains it probes entities using ai_visibility_check. However, it doesn't explicitly state when not to use it or mention alternatives, but the context is clear enough for the agent to infer when to choose this over sibling tools.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds important behavioral details: fans out across services, potential 5-30s delay for bundlephobia's first measurement, partial failure handling with sources_failed, and returned fields.

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

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

The description is a single paragraph, but every sentence adds value. It could be slightly more structured (e.g., bullet points), but it remains concise and readable. Minor deduction for length.

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

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

Given full schema coverage and annotations, the description covers purpose, usage, behavior, limitations, and output fields. No output schema exists, but the description lists returned fields, making it complete for an agent.

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

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

Schema coverage is 100%, so description adds limited value beyond schema. It mentions scoped packages are accepted and version defaults to latest, but these are minor additions. 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 it performs a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs like 'scan' and 'check', and distinguishes itself from sibling tools by targeting dependency analysis.

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 agent asks about safety, popularity, size, or cost of adding a package. Also sets boundaries: NPM only in v1, other ecosystems covered by deps.dev:version directly. Provides 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?

Beyond annotations (readOnlyHint, idempotentHint), it adds details about the embedding model (BGE-base-en), window size, character cap with truncation warning, and that it returns offsets for verification.

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 key purpose, each sentence adds distinct value: purpose, use case, benefits, technical details, pairing. No wasted words.

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

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

Despite no output schema, description explains return format (passages with offsets and scores) and the 200K char cap. Complete for a semantic search tool with clear inputs and 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%, so baseline 3. Description adds context for 'text' (the document to search), 'query' with examples, and 'limit' (max passages). The truncation note and offset info add value beyond schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples like SEC 10-K body. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says to use when the record is too large for the prompt, and recommends pairing with ask_pipeworx_grounded for grounding. Provides clear when-to-use and alternative.

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 (idempotentHint=true, readOnlyHint=false), the description reveals critical behaviors: requires OAuth account, returns subscription id, specifies delivery channels with constraints (SMS cap, phone verification, webhook auto-disable). 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 the core purpose and returns value, then logically covers prerequisites, types, and delivery channels. It is dense but each sentence earns its place; slightly long but efficient for the complexity.

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

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

The description is comprehensive for the tool's complexity: covers all parameters, prerequisites, and constraints. Lacking only a explicit mention of the return format beyond 'new subscription id' (no output schema) and error scenarios, but overall thorough.

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

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

Schema coverage is 100%, and the description adds substantial meaning: it provides examples for each type (e.g., sec_8k items, polymarket_edge topic), clarifies required vs optional fields in params, and details delivery channel semantics (verification, cap, webhook signing).

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes itself from sibling tools like `unsubscribe` and `list_subscriptions` 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 clear context for when to use the tool, including prerequisites (Pipeworx OAuth account) and supported subscription types. However, it does not explicitly state when not to use it or mention alternatives like recent_alerts for non-persistent polling.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds value by explaining the output format (category-bucketed example questions with tool+argument shapes) and that it draws from a live catalog, which goes beyond the annotation 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 longer but front-loaded with common user queries. Each sentence adds meaning; no waste. However, it could be slightly more concise without losing clarity.

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

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

Given low complexity (one optional param, no output schema, strong annotations), the description is complete: it explains when to use, what to expect, how to call with/without arguments, and connects to the broader tool ecosystem.

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

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

Schema coverage is 100% with one parameter described. The description adds focus area examples ('finance, pharma, economics...') and advises to omit for a spread, providing more practical guidance than the schema's brief 'Optional focus area'.

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

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

The description clearly states the tool returns example questions categorized by topic, serving as an onboarding entry point. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes from sibling tools like ask_pipeworx by positioning itself as the 'what can I ask' tool.

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

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

The description explicitly instructs to use this tool 'when you do not yet know what Pipeworx can do for you' or 'to learn how to call the meta-tools'. It provides clear context for when to use, though it does not explicitly mention when not to use or alternatives.

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

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

Beyond annotations (idempotentHint, destructiveHint), the description reveals that the row is deactivated (not deleted) and historical events remain available via 'recent_alerts', and that ownership is enforced.

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

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

Two sentences, no fluff. The most critical information (cancel by id) is first, followed by ownership and deactivation details.

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

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

Given the simplicity (1 parameter, no output schema) and presence of annotations, the description adequately covers behavioral context, side effects, and references to related tool (recent_alerts).

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 description is sufficient. The tool description does not add extra meaning beyond what the schema already provides for the 'id' 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 clearly states the action ('Cancel a subscription by id') and the specific resource (subscription for alerts). It is distinguishable from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description implies when to use (to cancel a subscription) and includes an important constraint (ownership enforcement). However, it does not explicitly discuss alternatives or exclusions, though the context is clear.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds substantial behavioral detail: the SEC EDGAR vs. grounded pipeline routing, the different verdict meanings, the critical caveat that could_not_verify means no check happened and must not be presented as evidence. It also clarifies the distinction from unsupported, which goes well beyond annotation 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 dense but every sentence adds necessary value: trigger phrases, usage guidance, pipeline breakdown, return values, and the critical error-handling caveat. It is front-loaded with examples, well structured, and free of 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?

With no output schema, the description fully compensates by explaining the return verdicts, the citation, the reasoning, and the meaning of each non-obvious verdict (could_not_verify vs. unsupported). It also covers routing and the tool's efficiency advantage, making it complete for an AI agent to invoke and interpret results correctly.

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

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

The input schema already provides 100% coverage of both parameters with clear descriptions and examples. The tool description adds no further parameter-specific semantics beyond what the schema already contains, so it meets the baseline but does not exceed it.

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

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

The description opens with explicit natural-language trigger phrases and identifies the core action: natural-language claim verification against authoritative sources. It clearly distinguishes the tool from siblings by stating it replaces 4–6 sequential calls, making its unique role 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?

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and describes two routing paths (company-financial vs. any other claim). However, it does not name alternative sibling tools or explicitly state when not to use it, so it falls short of full exclusionary guidance.

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