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 convey read-only, non-destructive, open-world behavior; the description adds useful context by revealing that the tool routes to 5,743 tools, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not contradict the annotations and provides behavior beyond what the structured fields state.

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 opening is front-loaded and effective, but the description becomes redundant: it repeats the 'START HERE' guidance and duplicates the entire example list near the end. This bloats the description and makes it less concise without adding new information.

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

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

For a tool with one required question parameter, the description is largely complete: it explains when to use the tool, what it does, how it returns results, and provides representative examples. The main gap is not addressing how the sibling variants (ask_pipeworx_beta, ask_pipeworx_grounded) differ from this one.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for a natural-language question. The description adds example queries and reinforces that the input should be a user-style question, but it does not add meaningful parameter-level semantics beyond what the schema already provides.

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

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

The description clearly identifies ask_pipeworx as a router that answers factual questions using authoritative, cited data and explicitly says to prefer it over web search. It enumerates many domains and gives concrete examples, making the tool's purpose scannable. However, it does not distinguish this tool from its siblings ask_pipeworx_beta and ask_pipeworx_grounded.

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

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

The description provides strong when-to-use guidance: it names web search as the alternative, lists trigger phrases like 'what is', 'look up', and 'get the latest', and tells the agent to 'START HERE for most questions'. It does not explain when to choose ask_pipeworx_beta or ask_pipeworx_grounded instead, so it stops short of a full 5.

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

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

Annotations already declare this as safe, idempotent, and non-destructive, so the description's job was to add behavioral context beyond that. It does so by disclosing that no candidate routing improvement is currently active, that the tool currently matches ask_pipeworx exactly, and that it is a full working router rather than a fallback. This is exactly the kind of state-specific transparency an agent needs.

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

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

The description is front-loaded with the key identity and behavior, and every sentence contributes useful context. It is slightly redundant in saying both 'identical universal router' and 'currently matches ask_pipeworx exactly,' but the redundant phrasing reinforces an important point for an experimental tool.

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

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

For a single-required-parameter router with full schema coverage and rich annotations, the description is nearly complete. It explains current beta status, usage equivalence, and comparison behavior. The only minor gap is that it references the response shape as 'same' as ask_pipeworx without describing it directly, which is acceptable if the sibling tool's description is available but not fully self-contained.

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

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

Schema description coverage is 100%, with aliases like q, text, input, and prompt fully documented. The description adds no new parameter semantics beyond saying 'same arguments' as ask_pipeworx, so the schema is already carrying the burden adequately.

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

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

The description clearly identifies the tool as the beta version of ask_pipeworx, a universal router over 5,743 tools, with the same arguments and response shape. It explicitly distinguishes itself from the stable ask_pipeworx by its experimental routing improvements and live-testing 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 tells the agent exactly when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to inform merges, providing clear context for choosing this beta tool over its stable sibling.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior, and the description adds substantial detail: it returns evidence as a verbatim quote, can refuse with structured reasons such as not_in_source or data_truncated, and never fabricates facts outside the tool result. It also discloses the cost tradeoff. 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 front-loaded with the core promise ('hallucination-resistant') and each remaining sentence adds a distinct fact: routing, output shape, refusal reasons, use cases, and cost comparison. The output-shape listing is justified because there is no output schema.

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

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

For a complex routing tool with no output schema, the description fully covers success and failure responses, evidence semantics, refusal reasons, when to use it, and how it differs from ask_pipeworx. The only missing detail is exact confidence semantics, which is minor.

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%: all six parameters are documented as aliases for 'question' and as natural-language input. The description adds no specific parameter syntax or format detail, but the schema already carries that burden, 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 names a specific behavior: a grounded answer mode that routes through Pipeworx, fetches data, and extracts an answer using only the tool result. It distinguishes itself from ask_pipeworx by emphasizing verbatim evidence and explicit refusals rather than free-form answers.

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 tells the agent exactly when to choose grounded mode — when the answer will be quoted, cited, or acted on, especially for financial, legal, medical, or public-statement contexts. It also gives an explicit exclusion: prefer ask_pipeworx for casual lookups because grounded mode costs one extra LLM call.

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?

Annotations already cover read-only, open-world, and idempotent hints, which the description complements rather than contradicts. The description adds substantial behavioral context: the tool decomposes questions into facets and routes them in parallel, returns explicit gaps[] for unanswered facets, never invents findings, does gap-recovery hops, detects contradictions, semantically excerpts rather than head-truncates large records, and has stated latency expectations (15-60s, ~90s for thorough). It also explains that citation_uri is present only when fetchable, preventing false expectations.

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

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

The description is long and dense, but nearly every sentence earns its place: account requirements, alternatives, scope, internal mechanics, return format, semantics of depth levels, citation behavior, and latency. It is front-loaded with the gating constraint (ACCOUNT REQUIRED) before anything else. It loses one point for general density and unanswered logical structure: the parenthetical 'depth:"thorough" needs a paid plan' interrupts and becomes slightly tangled given the later full explanation of depth levels.

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

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

For a complex, costly tool with two parameters, auth requirements, and no output schema, the description covers the essentials: what type of question it serves, what the results look like, what will be missing (gaps[]), how citations work, how long it takes, and how depth affects behavior. Nothing an agent needs to decide whether to call or select a depth value is missing; the absence of an output schema is compensated by the detailed findings-packet description.

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

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

Schema coverage is 100%, so the schema already documents both parameters in detail. The description adds value by explaining the behavioral meaning of depth values ('quick=3', 'standard=3 (default; adds gap-recovery hop...)', 'thorough=6 (paid; adds iterative hop...)') and reinforces that the question parameter accepts broad/multi-part natural language. Since the schema already covers the syntax and the description complements it with usage semantics, a 4 is appropriate; the only extra would be examples of multi-part question formatting.

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

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

The description states a specific verb ('research') and resource (1500 structured data sources via 5,743 tools), and distinguishes itself from open-web search and from ask_pipeworx. It clearly defines what the tool returns: a findings packet with verbatim evidence, confidence, source, citations, and gaps. The example question patterns make its purpose concrete and the 'NOT open-web search' warning sharpens its identity.

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 it ('broad/multi-part questions over structured data'), when NOT to use it ('single lookup' — use ask_pipeworx; 'BREAKING/CURRENT-NEWS' topics — prefer ask_pipeworx), and accounts for auth tiers ('ACCOUNT REQUIRED... If you are not signed in, use ask_pipeworx'). It also explains depth-level selection and what to expect from each tier, so an agent gets clear routing guidance without opening the schema.

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 mark it read-only/idempotent/non-destructive, and the description adds meaningful behavior beyond that: it runs sources in parallel, reports sources_used/sources_failed, treats empty sections as real 'no data' rather than errors, and returns resolved:false with a notes line for private companies. The patent soft-fail note is the kind of operational detail an agent needs.

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 information-dense, with the core purpose and routing rule front-loaded before source/output details. Minor redundancy exists because it repeats the type interchangeability that the schema already states, but every other sentence earns its place.

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

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

For a tool with no output schema, this is unusually complete: it enumerates returned fields (cik, company_name, resolved_from/to, recent_filings URIs, fundamentals items, each source section) and edge cases. An agent can predict both normal results and failure modes before calling.

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 documents both parameters at 100% coverage; the description adds the nuance that type 'company' and 'ticker' are interchangeable, gives concrete examples (AAPL, zero-padded CIK, Moderna), and clarifies name resolution via SEC EDGAR. This makes correct value construction easier than 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?

Describes exactly what it does: returns a full cross-source profile of a US public company from SEC, XBRL, patents, contracts, FDA, H-1B, news, and GLEIF. The opening examples ('Tell me about X', 'company profile for Microsoft') make the intended invocation unmistakable and distinguish it from narrower single-source tools.

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

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

Explicitly instructs agents to prefer this over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, which is strong routing guidance. It also covers input forms and the private-company fallback, so an agent knows when the tool can still be used rather than aborting.

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?

Annotations already establish a read-only, non-destructive, open-world profile, and the description goes far beyond that: it discloses the token-overlap matching mechanism, compatibility codes, fee grossness, unpaired leg handling, and the fact that returned pairs are unverified. It also carefully qualifies null temporal_alignment semantics.

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 deliberately structured into labeled sections (modes, response, safety fields, codes, fees, skips). Nearly every sentence conveys a necessary caveat or behavioral detail, so the length is justified by the tool's complexity, though it is denser than the typical tool description.

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

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

Despite having no output schema, the description covers the response shape, safety fields, flags, fee disclosure, skipped comparisons, and temporal alignment semantics in detail. For a tool with three optional parameters and nuanced cross-venue matching, this is a complete and self-sufficient description.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful operational meaning: it explains that kalshi_event_ticker and polymarket_event_slug override the topic mapping, that both modes use the same matcher, and that all parameters are optional. This is meaningful value beyond the schema.

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

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

The description clearly defines the tool as computing a cross-venue spread between Kalshi and Polymarket for the same resolving question. It names the exact resource and operation, and the emphasis on comparing the same question across two venues distinguishes it from Polymarket-only siblings 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?

It explains two distinct invocation modes (topic shortcuts vs explicit event identifiers), when each is appropriate, and warns that pre-mapped topics are not automatically tradeable. It does not explicitly name sibling alternatives to route away from, but the context for when to use this tool is strong.

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

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

Annotations already 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?

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description earns credit for going beyond them. It discloses how failures surface ('every identifier that could NOT be resolved is stated explicitly under `unresolved` rather than omitted'), graceful degradation ('LEI/FIGI enrichment degrades gracefully — if GLEIF or OpenFIGI is unavailable, the EDGAR identifiers still return'), ISIN-to-issuer semantics, and the fact that each call 'cascades through several lookup endpoints internally'. These are exactly the behavioral traits an agent cannot infer from 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 content is dense and every clause earns its place — identifier lists, failure semantics, and enrichment caveats are all substantive — and the key purpose is front-loaded. But the whole description is one ~250-word run-on paragraph with heavy parenthetical nesting inside the 'company' branch, making it harder for an agent to parse than a sectioned or bulleted layout would be.

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 high-complexity, two-type resolver with no output schema, the description is nearly complete: accepted input forms, the returned identifier set per type, LEI ownership enrichment (parent/ultimate-parent/children), the `unresolved` failure field, graceful degradation, and the RxNorm citation format. The only significant gap is the exact result shape for ambiguous name matches — the description mentions name search but never states whether candidates are returned for ambiguous names.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema: for 'company' it extends accepted inputs to include ISIN (the schema lists only ticker, CIK, or name) and explains what an ISIN resolves to — the issuing legal entity via the GLEIF mapping. This prevents an agent from wrongly rejecting a valid ISIN input based on 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 states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input', reinforced by concrete trigger phrases ('what's the ticker for…', 'find the CIK for…', 'look up the ID for…'). The line 'other tools require as input' plus the two SUPPORTED TYPES position it clearly as the identity-lookup gateway, distinguishing it from siblings like entity_profile or compare_entities that consume identifiers.

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

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

The description gives an explicit selection rule: 'Use FIRST whenever you have a name but need an ID.' The per-type input forms (ticker, CIK, ISIN, company name for company; brand or generic for drug) further narrow when the tool applies. However, it never names sibling alternatives or states exclusions (e.g., don't use when you already hold an ID), so it stays just below a 5.

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

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

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.