Openrouter

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it makes external calls to LLMs, the default model is free, and using Anthropic requires an API key with direct payment to Anthropic. This provides additional context beyond annotations.

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

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

Two sentences plus a use-case list. Front-loaded with action and output. Every sentence adds value: one for core functionality and output format, one for model/cost details, one for use cases. 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 having 4 parameters and no output schema, the description explains the return format (per-model {score, confidence, signals, raw_response} + combined view), default behavior, optional API key, and typical use cases. All necessary context is covered.

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 the purpose of each parameter: default model is free, _apiKey is needed for Anthropic, context helps disambiguate. This goes beyond the basic 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 probes LLMs for entity knowledge and returns a visibility score (0-100). It specifies the verb ('Probe'), resource ('LLMs'), and the output format. This distinguishes it from siblings like ask_pipeworx (which likely answers questions) and compare_entities (which compares entities).

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

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

The description lists explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to provide an API key for Anthropic. However, it does not explicitly state when NOT to use this tool or compare it to alternatives like ask_pipeworx or deep_research.

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, non-destructive, and idempotent, so the bar is lower. The description adds valuable context: it routes to 5,529 tools, fills arguments, and returns stable pipeworx:// citation URIs. No contradiction with annotations, and the added details clarify behavior beyond the structured 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 longer than average but well-structured and front-loaded with the key directive. It packs many useful details (domains, examples, alternatives) without redundancy. The 'START HERE' and 'Step up only when needed' breaks make it scannable.

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

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

Given the tool's high complexity as a meta-router, the description is remarkably complete: it covers supported domains, trigger phrases, example questions, the return format with citations, and clearly differentiates from heavier alternatives. No output schema exists, so the description carries the burden, and it does so thoroughly.

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

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

The input schema already covers all parameters with 100% description coverage, including aliases for the question field. The description provides three examples but no additional syntax or semantics beyond the schema, so it does not meaningfully raise the baseline.

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

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

The description clearly states it routes factual questions to specialized tools and returns structured answers with citations. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and the examples cover diverse use cases.

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 opens with 'PREFER OVER WEB SEARCH' and explicitly says 'START HERE' for most questions. It names alternatives with specific conditions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for multi-part questions. This is excellent when-to-use and 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?

Discloses that candidate routing improvements may be enabled live and that no candidate is currently active, so it matches stable. This adds valuable behavioral context beyond the annotations about the experimental nature of the tool. No contradiction with readOnlyHint, openWorldHint, or idempotentHint.

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

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

Three sentences, each serving a distinct purpose: definition, current status, and usage guidance. Every sentence earns its place, with no redundant information or 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?

The description covers the beta nature, current behavior, relationship to the stable router, and clarifies it operates fully. It also notes the response shape is identical to ask_pipeworx, providing sufficient context despite the absence of an output schema.

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

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

The schema fully documents all six parameters with 100% coverage, so the description need not repeat them. The description does not add parameter-level detail, but the alias relationships are clearly conveyed in the schema, making the baseline score of 3 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 identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools and arguments. It distinguishes from siblings by emphasizing the experimental edge and candidate routing improvements. The purpose is clear, though the verb is implicit rather than explicit.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts with the stable router. It also clarifies the current state (no active candidate) and that it's a full working router, not a fallback, providing clear when-to-use and 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 safe, idempotent, read-only behavior. The description goes far beyond by disclosing the exact refusal reasons ('not_in_source', 'no_tool_match', etc.), the output structure, and the extra LLM call cost. It also clarifies that the tool will not fabricate facts by extracting only from the tool result. 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 dense but every sentence serves a purpose: purpose, mechanism, output contract, refusal-engaged circumstances, and cost tradeoff. The refusal enum list is verbose but critical for correct agent behavior. It is front-loaded with the core value proposition and structured logically from behavior to usage to alternative.

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 fully compensates by specifying success and failure return shapes, including the possible refusal_reason values. It also addresses the key contextual concern: when to use this instead of ask_pipeworx. The complexity of the tool (with routing, extraction, and refusal logic) is fully covered.

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 is fully described at 100% coverage, with six aliases all documented as natural-language question formats. The description adds no parameter-specific detail, but none is needed because the schema covers all parameters. Baseline 3 is warranted since the description doesn't enhance parameter understanding, though the existing schema is sufficient.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' with a specific mechanism: it extracts answers using ONLY the tool result, and explicitly contrasts itself with ask_pipeworx. The verb phrase 'EXTRACTS the answer' plus the refusal behavior makes the tool's purpose unmistakable and distinguishes it from siblings.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists concrete high-stakes domains. Also gives a when-not-to-use rule and names the alternative: 'prefer ask_pipeworx for casual lookups' due to cost. This is exactly the kind of decision guidance needed.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds extensive behavioral details beyond annotations, including fan-out logic, resolver contract, parent event extraction, news fallback handling, safety mechanisms, and resolution-rule risk. No contradictions.

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

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

The description is lengthy but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). While comprehensive, it could be more concise; each sentence adds value, but the overall length is high.

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

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

Given the tool's complexity and no output schema, the description covers input handling, output structure, edge cases (low confidence, closed markets, wide spreads), safety, and resolution rules. It is fully self-contained and leaves no critical gaps.

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

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

Schema coverage is 100% with descriptions. The description significantly adds value by explaining the 'market' parameter accepts multiple formats (slug, URL, question text), the 'depth' parameter's quick vs thorough modes, and 'include_raw' with details on response sizes and use cases.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes itself from sibling tools by focusing specifically on Polymarket bets with a dedicated pipeline.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y') and examples. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling context implies other research tools exist.

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, openWorldHint), the description adds rich behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific financial metrics, off-calendar fiscal year handling, sorted results, and citation URIs. This fully informs the agent.

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 compact (about 6 lines) yet densely informative. Every sentence adds value: synonyms for natural language, efficiency claim, entity-specific details, and output format. No redundant or missing information.

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

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

Given no output schema, the description adequately describes return value (paired data + citation URIs). It covers both entity types, explains sorting by primary metric, and highlights efficiency. For a 2-param tool with simple schema, this is 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?

The input schema already describes both parameters with enums and descriptions. The description adds context by linking type to entity behavior (company vs drug), examples (tickers/CIKs, drug names), and constraints (minItems 2, maxItems 5). It enhances understanding.

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs in one parallel call. It includes specific verb phrases ('Compare X and Y', 'rank these companies') and distinguishes from sequential lookups, leaving no ambiguity.

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 when-to-use guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also gives example natural language triggers. However, it does not explicitly state when not to use (e.g., for single entity lookups), but the preference is strong enough.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safety. The description adds 'Keyless', implying no authentication needed, and details the comparison dimensions (pricing, context window, modality), which are not in annotations. No contradictions.

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

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

Two sentences, no filler. All information is front-loaded and essential: comparison scope, what is compared, an example, and a note on authentication.

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 hints at the output (side-by-side comparison of three attributes). It covers intended use well but lacks explicit return format details.

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

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

Schema coverage is 100% with a clear description of 'ids' as an array of exact model ids. The description reinforces the 2-5 constraint and provides examples, but does not add new meaning beyond the schema.

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

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

The description uses a specific verb ('Side-by-side comparison'), identifies the resources (pricing, context window, modality), and constrains scope (2-5 OpenRouter models). The example question clarifies intent and distinguishes from siblings like list_models and get_model.

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

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

The description implies use for comparing model pricing, context window, and modality, exemplified by the question. It does not explicitly state when not to use or name alternatives, but sibling names provide 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?

The description adds extensive context beyond the annotations: account requirements, time expectations, return packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] behavior, contradictions[], hop field, citation_uri guarantee, and semantic excerpting. It is consistent with the readOnlyHint and does not contradict any annotations.

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

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

The description is long but every sentence adds critical information: account requirements, alternatives, capabilities, limitations, parameters, and behavior. It is front-loaded with the account requirement, and the structure flows logically. It is appropriately sized for a complex tool like this.

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, the absence of an output schema, and rich annotations, the description is complete. It explains the return package, gaps[], contradictions[], latency, and the distinction from open-web search. It covers auth, parameter semantics, and use cases thoroughly.

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

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

Schema coverage is 100%, and the description further elaborates on the depth parameter by explaining what each depth setting does (quick/standard/thorough with gap recovery and follow-up hops). The question parameter is described as natural language, which is adequate. The description adds valuable meaning beyond the schema.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's structured data sources in one call, and explicitly distinguishes itself from ask_pipeworx and open-web search. It uses a specific verb ('researches'), a clear resource (structured data sources), and differentiates from sibling tools by noting its decomposition and parallel routing capabilities.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also includes an account requirement note directing unsigned-in users to ask_pipeworx, and clarifies depth tiers.

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. Description adds valuable behavioral details: returns top-N tools with names, descriptions, and full input schemas with curated examples, ready to call.

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 front-loaded with purpose, then usage, then return details. While slightly verbose, each sentence adds value, making it effective and well-structured.

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

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

Given no output schema, the description explains the return format sufficiently. With 6 parameters (mostly aliases) and clear usage guidance, the definition is complete 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 coverage is 100% with descriptions for each parameter. The description adds context beyond schema by explaining query expects natural language and providing examples, enhancing agent understanding.

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

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

The description clearly states the tool finds tools by describing data or task, lists many example domains, and distinguishes from siblings by advising to call this FIRST to see the option set.

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

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

Explicitly states when to use (browse, search, look up, discover tools) and calls out to use FIRST when many tools are available, providing clear usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like patent API sunset and news fallback, which are beyond what annotations provide. No contradiction.

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

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

The description is well-structured with front-loaded examples and clear statements. It is somewhat long but every sentence adds value; a bit of redundancy in listing return fields could be tightened.

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 exists, so the description must cover return values. It does so thoroughly, listing all returned fields (cik, filings, fundamentals, patents, news, LEI) and their sources, making the tool fully understandable.

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

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

Schema coverage is 100% with both parameters described. The description reinforces that type only supports 'company' and value must be ticker or CIK, adding the important constraint that names are not supported.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example queries and lists specific data sources, distinguishing it from siblings like resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and warns that 'names not supported (use resolve_entity first if you only have a name).' This provides clear when-to-use and 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 provide destructive and idempotent hints. The description adds context about clearing sensitive data, but doesn't disclose additional behavioral traits beyond that.

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 core purpose, no wasted words. Every sentence is informative.

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

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

For a simple, single-parameter tool with clear annotations and schema, the description covers all necessary context including usage scenarios and sibling references.

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

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

Schema coverage is 100% and the parameter is adequately described; the description adds no extra semantic value beyond the schema.

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

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

The description clearly states the action ('Delete') and resource ('previously stored memory by key'), and distinguishes from sibling tools like 'remember' and 'recall'.

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

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

Explicitly provides when-to-use scenarios (stale context, task done, clear sensitive data) and mentions pairing with siblings, guiding appropriate invocation.

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

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

The description explains the tool's behavior: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown. This adds context beyond the annotations (which already indicate read-only, idempotent, non-destructive behavior). The description aligns with the annotations without contradiction.

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

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

The description is three sentences long, with no superfluous words. It immediately states the core purpose and follows with behavioral details and usage examples. Every sentence adds value, making it highly efficient for an AI agent to parse.

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 fairly complete given the tool's complexity: it specifies input, process, output format, and use cases. However, it does not mention error handling (e.g., invalid URLs) or edge cases like pages without meta tags, which would add robustness. With no output schema, the description should ideally cover the output format more explicitly, though it does state 'single text blob ready to drop at site-root/llms.txt'.

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

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

Schema description coverage is 100% and both parameters ('url' and 'max_links') have clear descriptions in the schema. The tool description does not add any semantic information beyond what the schema already provides. The baseline score of 3 is appropriate since the description adds no extra value for parameter understanding.

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

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

The description clearly states the tool generates an llms.txt file for a given URL, using specific verbs ('Generate', 'fetches', 'extracts', 'emits') and the resource 'llms.txt file'. It distinguishes itself from sibling tools by focusing exclusively on llms.txt generation, while other tools like ai_visibility_check or scan_competitor_ai_presence serve different purposes.

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 three concrete use cases (client indexing, own project drafting, competitor auditing) that clearly indicate when to use this tool. However, it does not explicitly mention when not to use it or name alternatives for related but different tasks, such as using ai_visibility_check for a simpler presence check.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, making the safety profile clear. The description adds value by noting that the tool is 'Keyless' (no authentication required) and listing the data returned, which goes beyond annotations.

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

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

Description is a single, well-structured sentence that front-loads the purpose and includes key details without wasted words. Every part 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?

Given the simple input schema (one parameter) and no output schema, the description adequately explains the tool's purpose, return fields, and the keyless nature. It is complete for an agent to understand and use the 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 the parameter is well-documented in the schema. The description provides an example and the 'Keyless' note, but adds minimal meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states it retrieves full details for one OpenRouter model by id, listing specific fields (pricing, context window, etc.). This distinguishes it from sibling tools like list_models and compare_models.

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 implies usage for fetching details of a single model, and provides an example. However, it does not explicitly state when not to use it or mention alternative tools like list_models for overviews or compare_models for comparisons.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that results are sorted cheapest-first and require no keys, but does not disclose pagination or rate limits. Value is added but limited given annotation coverage.

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

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

The description is two sentences, front-loading the main purpose. It is concise and includes key details without extraneous text. Slight improvement could be breaking into shorter 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?

Despite lacking an output schema, the description summarizes what is returned (pricing, context windows, modality). Parameters are well-covered. The tool is a simple listing, so completeness 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 coverage is 100% with each parameter described. The description adds value by providing examples and clarifying default/max for limit, and usage hints like 'free_only' meaning $0 prompt price. This adds meaning beyond the schema.

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

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

The description clearly states the tool lists LLMs from OpenRouter catalog with specific attributes like pricing, context windows, and modality. It is a specific verb+resource and distinguishes itself from broader tool context.

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

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

The description provides filtering options and notes it is keyless, but does not explicitly state when to use this tool versus alternatives like get_model or compare_models. Usage context is inferred but not clearly delimited.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds return fields and parameter context but does not contradict annotations. With annotations covering safety, description adds moderate value.

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, front-loaded with purpose and return fields. Efficient and easy to parse.

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?

Low complexity (1 optional param, no output schema). Description covers purpose, usage, return fields, and parameter. Adequately complete for the tool's scope.

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 'active subscriptions' implying default behavior, which adds minor context beyond the schema's parameter 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?

Clearly states the verb 'List' and resource 'subscriptions', specifies it returns caller's active subscriptions, and lists returned fields. Distinguishes from sibling tools 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?

Explicitly advises using this tool to review monitored subscriptions before adding more or to find an id to cancel. Provides clear context for when to use it, though no explicit when-not statement.

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 and offer no safety hints, so the description carries the full burden. It discloses the claim_token flow ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'), rate limits ('Rate-limited to 5 per identifier per day'), and quota impact ('Free; doesn't count against your tool-call quota'). This is rich behavioral context beyond what annotations provide.

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

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

The description is appropriately sized for the tool's complexity. It is front-loaded with the core purpose, then usage guidelines, exclusions, token mechanics, and operational notes. Every sentence adds distinct value — no filler or repetition. The logical flow from what → when → how → constraints is exemplary.

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 moderate complexity (nested context object, enum, conditional claim_token behavior) and the absence of an output schema, the description covers all critical aspects: what feedback types exist, how to provide context, the token-based response mechanism, rate limits, and scope boundaries. It is complete enough for an agent to invoke the tool correctly without further clarification.

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

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

The schema already has 100% coverage of all 4 parameters, so the baseline is 3. The description adds meaning beyond the schema by explaining the claim_token usage in context ('pass the pwfb_… token that filing returned, with no other arguments') and clarifying the intended message specificity. This extra semantic guidance justifies a 4, though the schema does most of 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 states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team), the action (tell/send feedback), and distinct categories (bug, feature, data_gap, praise). This distinguishes it effectively from all sibling tools, none of which are feedback-related.

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

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

The description provides explicit when-to-use guidance for each feedback type ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well'). It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This is ideal usage guidance with alternatives and 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?

The description adds value beyond annotations by disclosing that data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h. Annotations already indicate readOnly, idempotent, openWorld, and non-destructive nature, so the description supplements 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 concise (3-4 sentences), front-loaded with the main purpose, and every sentence earns its place. No redundant or vague phrasing.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description explains the return values (top tools, top packs, call volume), caching, and data source. It could be slightly more detailed about the return structure, but it is largely sufficient.

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

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

The input schema covers 100% of the single parameter with enums and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps the agent choose appropriately.

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 recent window. It uses specific verbs ('returns') and resource ('Pipeworx trending'), and it is distinct from sibling tools like 'discover_tools' which are for different purposes.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment) and explains the difference between short and long windows. However, it does not explicitly state when not to use this tool or compare it to 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 readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: threshold details (3pp, 0.30 Jaccard), placeholder filtering, fill check logic, and fallback behavior. It 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?

The description is very long and detailed, which provides completeness but sacrifices conciseness. It is well-organized with logical sections, but could be trimmed for quicker scanning by an AI agent.

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

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

Despite lacking an output schema, the description thoroughly details the response structure (opportunities[], partition_check object, fill check results) and covers edge cases, semantic anchors, and filtering rules. It is fully self-contained for an agent to use correctly.

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

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

Input schema has 100% description coverage for both parameters, but the tool description adds substantial meaning beyond the schema: examples of valid values ('fed-decision-may-2026'), the purpose of each parameter, and how they affect scanning behavior. This enriches understanding but is somewhat verbose.

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 (trending_scan, event, topic), making the purpose and scope unambiguous.

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

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

Explicit guidance is given for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises when not to execute a trade based on the fill check results and references polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond, detailing caching behavior (1h at KV level), edge computation methodology, slippage handling, Kelly sizing, and warnings like 'your edge may already be in the price'. 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 (over 400 words) and dense with technical details (FRED log-returns, GDELT, Kelly formulas). While well-organized into segments and knobs, it could be more concise for an AI agent, reducing cognitive load.

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), the description is remarkably complete. It covers purpose, all behavioral details, response structure (including diagnostics for empty segments), caching, and tradeable-edge knobs. Nothing essential is omitted.

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 extra context for many parameters (e.g., slippage_pp explains trading fees, min_liquidity explains walking the book, min_partition_leg_kelly explains why min_kelly doesn't apply). This adds value beyond the schema alone.

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

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

The description explicitly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a clear use case 'what should I bet on today'. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovering opportunities without paging.

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 (discovering opportunities) and details on each segment and knob usage. However, it lacks explicit exclusions or comparisons to alternative tools, such as when to prefer polymarket_arbitrage over this one.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive. Description adds valuable behavioral details like response structure, signed edge_pp_net, decay computation from daily closes, and snapshot TTL limits.

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?

Compact yet comprehensive; each sentence serves a purpose. Structured with clear section on args and response fields (tracked, expired, snapshot_dates). 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?

Fully explains tool purpose, parameters, response format, and limitations given no output schema. Covers edge cases like gaps in snapshot dates and decay calculation caveats.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description largely restates parameter info (defaults, ranges) without adding significant new semantics, meeting the baseline.

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

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

Clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. Contrasts fresh vs old edges, distinguishing it from sibling tools like 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?

Implies usage for historical edge analysis with examples of fresh vs old edges, but lacks explicit when-to-use or when-not-to-use instructions relative to alternatives.

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

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

The description adds significant behavioral context beyond annotations: it walks the order book ladder, returns specific fields (top_of_book, slippage, etc.), and warns about the dominant loss mode. Annotations already indicate read-only, idempotent, non-destructive, so 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 well-structured with headings and bullet points, front-loading the purpose. It is thorough but not overly verbose; every sentence adds value. Minor room for tightening, but otherwise efficient.

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

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

Despite no output schema, the description lists all return fields in parentheses. It covers two modes, parameter nuances, and risk warnings. Given the tool's complexity, this description is comprehensive and leaves no critical gaps.

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

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

Schema coverage is 100%, but the description enhances meaning: it explains side default behavior (auto in basket), size_usd interpretation (spend vs target proceeds), and mode-specific implications. This goes 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 performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market vs basket). It provides specific verb and resource, differentiating it from sibling tools 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 tells the agent when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why (partial basket fills convert arb into unhedged position), providing clear context and alternatives.

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

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

The description adds extensive behavioral context beyond the annotations (readOnlyHint, etc.). It details how the tool handles equivalent vs non-equivalent bet shapes, the conditions for compatibility_warning, temporal alignment constraints, and skipped cross-type/subtype counters. This fully informs the agent of the tool's behavior and limitations.

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 lengthier than average but well-structured with clear sections (modes, response, safety fields). Every sentence contributes useful information. Minor redundancy could be trimmed (e.g., repeating 'pre-mapped ≠ tradeable'), but overall it is 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?

Given the complexity of cross-venue spread calculations and the absence of an output schema, the description provides comprehensive information about the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and edge cases. It fully covers what the agent needs to interpret the 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. The description adds value by explaining the topic shortcuts' exact list and how explicit tickers override the topic-mapped side. It also notes that topic and explicit parameters are mutually exclusive in usage. However, it does not provide further syntax details 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 computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on venue comparison rather than single-venue arbitrage. The two modes (topic shortcuts and explicit tickers) are clearly explained.

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

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

The description provides explicit guidance on when to use the tool and scenarios to avoid. It warns that most pre-mapped topics return compatibility_warning and are not necessarily tradeable, and explains the meaning of safety fields like compatibility_warning and temporal_alignment. This helps the agent decide when the output is meaningful.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context about scoping to an identifier and pairing with remember/forget, which goes beyond annotations and does not contradict them.

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

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

The description is three sentences, front-loaded with the core purpose, followed by usage context and pairing. Every sentence adds value, and there is no wasted wording.

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 low complexity (1 optional parameter, no output schema). The description sufficiently explains what the tool returns (a value or a list). It is complete for an AI agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that omitting the key lists all saved keys, and that the key is optional. This helps the agent understand parameter behavior 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 retrieves a value saved via remember or lists all keys, with a specific verb-resource pair. It distinguishes from siblings remember and forget by explicitly naming them.

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

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

The description explains when to use (look up context stored earlier) and pairs with remember/forget. It does not explicitly state when not to use, but the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavior: mark_read flips a flag so subsequent calls return newer events only; alerts carry specific fields; and the same feed is available at a REST endpoint. No contradictions.

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

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

The description is efficient (3-4 sentences), front-loaded with the core action, and each sentence adds distinct information without redundancy. 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?

The description covers what the tool returns, filtering options, the mark_read behavior, and even an alternative access method. It is complete for a read-only, idempotent tool, though it could mention pagination or ordering more explicitly (but 'most recent' is implied).

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

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

Schema coverage is 100% with parameter descriptions, but the description adds context: e.g., 'Filter by type (e.g. "sec_8k")' and explains the effect of mark_read (makes next call show only newer events). 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 'Pull fired events from your subscription feed' and details what is returned (source, citation_uri, raw payload) and how to filter. It distinguishes itself from sibling tools like 'list_subscriptions' or 'subscribe' by focusing on reading events.

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

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

The description explains when to use the tool (fetching recent alerts) and mentions that polling works fine, implying suitability for repeated calls. It also notes an alternative REST endpoint for scripts and dashboards, but does not explicitly state when not to use this tool or compare with other read tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds rich behavioral details: fan-out to multiple sources, fallback logic, soft-fail for USPTO due to API sunset, accepted date formats (ISO and relative shorthands), and return structure (grouped changes, count, citation URIs). No contradiction with annotations.

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

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

A single, well-structured paragraph that front-loads the purpose with examples, then details sources, parameters, return format, and usage guideline. Every sentence adds value; no redundancy or fluff.

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

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

Given the complexity (3 parameters, multiple data sources, fallback, no output schema), the description covers: purpose, sources, parameter semantics, error handling (soft-fail), return structure, and distinguishes from a sibling tool. Fully sufficient 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 covers all 3 parameters fully (100% coverage). The description adds value beyond the schema by giving example values for 'since' (e.g., '30d', '1m') and explaining that 'value' accepts ticker or zero-padded CIK, which aids correct usage.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists specific sources (SEC EDGAR, GDELT/GNews, USPTO). It starts with example queries that clarify the use case, and distinguishes from the sibling tool 'entity_profile'.

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

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

The description ends with an explicit when-not-to-use: 'Use entity_profile instead when you want the static profile'. It also provides examples of when to use, and explains the fallback behavior (GDELT preferred, GNews on rate limit/5xx), giving clear 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?

Beyond annotations (idempotentHint=true, destructiveHint=false), the description discloses scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions, adding valuable behavioral context.

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

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

The description is concise (~50 words), front-loaded with main purpose, followed by usage guidance, examples, and pairing with sibling tools. Every sentence is necessary and well-structured.

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

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

Given the simplicity of the tool (2 params, no output schema), the description fully covers purpose, usage, behavior, and pairing with related tools. No gaps remain.

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

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

Schema coverage is 100% with parameter descriptions. The description adds usage context (e.g., scoping) but does not significantly enhance meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Save data') and resource ('the agent will need to reuse later') and distinguishes from sibling tools like 'recall' and 'forget' by pairing with them.

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

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

The description provides clear guidance on when to use ('when you discover something worth carrying forward') and gives examples, but does not explicitly state when not to use or list alternative tools beyond recall/forget.

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 read-only/idempotent annotations, the description discloses several important behaviors: identifiers are labelled with their source, unresolved identifiers are listed under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully, and each call cascades through multiple endpoints. These details are not visible in annotations or 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 longer than average but well-structured: opening examples, core purpose, usage instruction, then a supported-types list with bolded labels. Each section adds unique information. A minor redundancy is restating accepted company inputs, but overall it is concise relative to the complexity it covers.

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

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

Given the tool has no output schema, the description fully compensates by explaining return behavior (labelled identifiers, explicit unresolved field), graceful degradation when external sources are down, and internal cascading. It covers both entity types thoroughly. This is sufficient for an agent to know what to expect and when to use the 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?

While the schema already covers 100% of parameter descriptions, this description adds substantial semantic value. For `type: company` it details the cross-source identity spine (CIK, ticker, LEI, FIGI) and for `type: drug` it specifies RxCUI, ingredient, brand, and citation format. It also clarifies accepted input variations for `value` beyond the schema examples.

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

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

The description clearly states the tool's purpose: resolving a user-spoken name to canonical identifiers required by other tools. It provides concrete example queries and explicitly says 'Use FIRST whenever you have a name but need an ID,' which distinguishes it from sibling tools that consume IDs.

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?

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID' and it lists supported entity types with accepted input formats (ticker, CIK, name for company; brand/generic for drug). This clearly tells an agent when to invoke this tool versus alternatives that require already-resolved IDs.

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, idempotent, etc. The description adds behavioral detail: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density, going beyond annotations.

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

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

Three sentences, front-loaded with purpose, each sentence adds value without redundancy. Concise and 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?

Despite no output schema, the description explains the return format (ranked list with score, confidence, signal density) and internal process (probes with ai_visibility_check). Complete for a tool with moderate complexity.

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

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

Schema coverage is 100%, but the description adds value by explaining that the first entity is treated as the 'subject' for narrative and rest as competitors, which is not in schema. Provides additional context for the 'context' parameter as disambiguation.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side using ai_visibility_check and ranks them, which is specific and distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

Provides a clear use case for competitive AI-marketing audits ('does Claude know about us as well as our competitors?'), but does not explicitly mention when not to use or list alternative tools for single-entity checks, though implicit from sibling 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?

Disclosed beyond annotations: composite fan-out to two services, partial failures degrade gracefully, first-time bundlephobia measurement can take 5-30s, and sources_failed reports timeouts. No contradiction with readOnly/idempotent/destructive 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?

Well-structured and front-loaded: first sentence defines purpose, then details checks, usage, constraints, output summary, and failure behavior. Every sentence adds value, no redundancy.

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

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

Output shape is fully described (summary block with specific fields, per-advisory detail, links, alternative versions) despite no output schema. Covers complexity of composite call, timing, and graceful degradation.

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?

Adds context beyond schema: scoped packages accepted (e.g., @types/node), version defaults to latest, and clarifies that package is a name string. Schema coverage is 100% but description enriches meaning.

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 covering license, advisories, and bundle size. It uses specific verbs and resources ('scan dependency') and distinguishes from sibling tools through its focus on npm ecosystem 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 an agent asks is X safe/popular/small or what does adding lodash cost me'. Also clarifies scope (NPM only in v1) and directs to deps.dev for other ecosystems, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral details: embedding model (BGE-base-en), chunking strategy (overlapping 500-char windows, cosine similarity), character cap (200K chars with truncation and flagging), and output specifics (character offsets, similarity scores).

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then provides usage guidance, then technical details. Every sentence adds value, with no wasted words or 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?

Given no output schema, the description explains the return values (top-N passages with offsets and scores). It covers all aspects: what the tool does, when to use it, technical implementation, limitations (cap and truncation), and integration with sibling tools. For a tool with three parameters and no output schema, this is comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: examples for the text parameter (SEC 10-K body, article) and query parameter ('supply-chain risk', 'fiscal year 2024 revenue'), and explains the default and range for limit. This enriches the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It specifies the verb (search inside), resource (a record), and scope (semantic search). It also differentiates from sibling tools like ask_pipeworx_grounded by mentioning their pairing.

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 when to use this tool: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It does not provide explicit when-not-to-use scenarios or alternatives, but the context is clear and sufficient for an agent.

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

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

The description adds behavioral context beyond annotations, such as OAuth requirement, SMS rate limit (10/day), webhook secret returned only once, and always-on feed. Annotations declare idempotentHint=true, which aligns with the description. No contradictions.

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

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

The description is well-structured with a clear purpose, detailed type enumeration, and delivery options. While verbose, each sentence adds value; 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 no output schema, the description covers return values (subscription ID), all parameter details, behavioral nuances (e.g., webhook signing secret), and constraints. It fully equips the agent to understand the tool's operation.

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?

Despite 100% schema coverage, the description enriches parameter meaning with concrete examples, constraints like phone verification, webhook HTTPS-only, and type-specific parameter structures. This goes beyond the schema's bare 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 defines the tool as creating a proactive monitoring subscription to live-data event streams and returning a subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying its unique function.

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

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

The description states when to use the tool (e.g., for setting up alerts) and prerequisites (Pipeworx OAuth account). It provides guidance on subscription types and delivery channels, but lacks explicit exclusion of when not to use it in favor of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description's safety profile is clear. The description adds valuable behavioral context: it returns category-bucketed example questions from a live catalog and can be focused with a topic. No contradictions.

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

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

The description is a single dense paragraph, but it is efficient and front-loaded with the key purpose. Every sentence adds value, and the structure is clear despite being prose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool returns, how to call it, and its role as an onboarding tool. No gaps are apparent.

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 meaningful guidance: it lists example topic values (finance, pharma, etc.) and explains that omitting the topic gives a cross-category spread. This goes beyond the schema's simple 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's purpose: an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from siblings by being the first tool to use when the agent doesn't know what Pipeworx can do.

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

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

The description explicitly instructs to use this tool first when you don't know what Pipeworx can do, and to learn how to call meta-tools. It also explains how to call with no arguments for full spread or with a topic to focus. No explicit when-not or alternatives are given, but the context implies it's for exploration.

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 show non-destructive and idempotent hints, but the description adds crucial context: ownership enforcement, deactivation vs. deletion, and effect on historical events, which are not captured in annotations.

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

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

Three efficient sentences front-load the action, with no redundant words. Every sentence adds distinct information without verbosity.

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 no output schema, the description fully explains the behavior, side effects, and ownership constraints, leaving no gaps for an agent to misunderstand.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The description adds value by linking the id to the subscribe tool's return, though it does not provide additional format or constraints beyond the schema.

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

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

The description explicitly states 'Cancel a subscription by id' with a clear verb and resource, and it distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation behavior.

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

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

It provides explicit guidance on when to use the tool ('you can only cancel your own subscriptions') and explains the outcome ('deactivated, not deleted'), helping the agent decide when this tool is appropriate over 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?

Despite annotations already marking the tool as read-only, idempotent, and non-destructive, the description adds crucial behavioral context: it explains the meaning of 'could_not_verify' (check did not happen, must not be used as evidence) and 'unsupported' (no source covered), plus the tolerance_pct override behavior. This goes well beyond the annotations.

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

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

The description is long but every sentence carries useful information. It is front-loaded with trigger phrases and purpose, and the detailed verdict/error explanations are valuable. It could be restructured for easier scanning, but it is not bloated.

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 two-parameter tool with no output schema, the description fully covers return values (verdict, cited value, reasoning), error semantics, and special cases. It also explains the two execution paths, making it complete for an 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?

Schema coverage is 100%, but the description enriches parameter understanding: it explains how tolerance_pct overrides claim wording, suggests setting 1–2 for hallucination detection, and clarifies the default cap of 5. This adds practical guidance beyond the schema's basic definitions.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources, with specific trigger phrases and examples. It distinguishes itself from siblings by emphasizing it replaces a multi-step pipeline and covers both structured SEC/EDGAR and general factual claims.

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 provides an explicit 'Use whenever the agent needs to check whether something a user said is factually correct' and details the routing logic for different claim types. However, it does not name sibling tools or explicitly state when not to use it, so it lacks the explicit alternative differentiation seen in top-tier examples.

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