Openverse

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

The description adds significant behavioral details beyond annotations: default model (Workers AI Llama-3.3-70b free), optional Anthropic probing requiring an API key (with cost implication), and return structure (per-model score, confidence, signals, raw_response). Annotations indicate idempotent and read-only, which aligns with the described behavior.

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

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

The description is concise: two sentences. The first sentence states the core purpose and default model. The second covers extension with API key and return format. No filler 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 4 parameters (one required), no output schema, and annotations providing safety cues, the description fully covers what the tool does, how parameters affect behavior, and what the response looks like. Usage contexts are also provided.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds value by explaining the purpose of 'models' (which models to probe), '_apiKey' (BYO key for Anthropic), and 'context' (disambiguation aid). This enriches the schema info.

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 probes LLMs to score visibility (0-100) for a business/brand/product/topic. The verb 'probe' and resource 'LLMs for visibility score' are specific and distinct from sibling tools like scan_competitor_ai_presence or compare_entities, which focus on different aspects.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It implicitly distinguishes from siblings by focusing on LLM knowledge visibility, but does not explicitly state when not to use or list alternative tools. However, 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 indicate readOnly, openWorld, idempotent. Description adds that it routes to many sources, returns citations (pipeworx:// URIs), is fast, and works on all tiers—no contradiction.

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

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

Description is dense but front-loaded with key message. Every sentence adds value, though slightly long. Could be more concise but well-organized.

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

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

Given the complexity (meta-tool with many sub-tools), the description covers what happens (routing), output format (structured answer with citations), and when to use alternatives. No 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 has 100% coverage with descriptions for all 6 parameters (aliases for question). Description adds context that the question should be natural language and factual, but no additional depth per parameter. Score 4 for adding usage context beyond schema.

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

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

The description clearly states the tool routes questions to 4,774 tools across 1242 sources and returns structured answers with citations. It explicitly distinguishes from siblings like web search and other 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 says 'PREFER OVER WEB SEARCH' for factual questions, provides specific examples, and directs to alternatives (ask_pipeworx_grounded, deep_research) when needed.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds key behaviors: hallucination resistance, extraction from tool result only, explicit refusal reasons (not_in_source, no_tool_match, etc.), and the routing across 4,774 tools. 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?

Description is front-loaded with the key concept and structured logically: purpose, process, output format, use cases, trade-off. Every sentence adds value, though slightly verbose for the aliases list.

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 format, refusal reasons, and comparison to ask_pipeworx. Lacks discussion of rate limits or pagination, but annotations fill some 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 each alias described. Description does not add extra constraints or examples beyond the schema, but contextualizes that the question is used to select the right tool and fill arguments. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads', explains its process (same routing as ask_pipeworx, then extraction from tool result only), and specifies the return format. It distinguishes from the sibling ask_pipeworx.

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 to use this tool when answers will be quoted, cited, or acted on (e.g., financial verdicts, legal claims) and to prefer ask_pipeworx for casual lookups, citing a cost trade-off of 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read-only behavior. The description adds minimal extra behavioral context beyond stating it takes an audio ID and returns related audio.

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

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

Two concise, front-loaded sentences that effectively communicate the purpose without unnecessary detail. Every 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 simple tool with 1 parameter and an output schema, the description covers the core function and use case. It does not mention pagination or limits, but output schema likely handles result structure.

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

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

Schema description coverage is 0%, so description must compensate. It mentions 'given Openverse audio ID' and the schema example shows UUID format, but the description does not reinforce the format or provide additional semantics about the input.

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 'find', the resource 'audio similar to [X]' (related audio), and the context 'Openverse audio ID'. It distinguishes from sibling tools like get_audio and search_audio by focusing on similarity exploration.

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 case: 'for similarity exploration in CC audio.' It implies when to use this tool over others, but does not explicitly mention when not to use or name alternatives directly.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description extensively discloses behavioral traits: fan-out logic per category, response shapes, safety mechanisms (low-confidence resolution, closed markets, wide spread), cancellation rule parsing, and resolution contract. It fully informs the agent of all important behaviors.

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

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

Though lengthy, every sentence adds necessary value. The description is front-loaded with the core purpose and then systematically covers inputs, fan-out examples, response shapes, safety, and edge cases. It is well-structured and avoids 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 the tool's complexity, the description is remarkably complete. It covers all aspects: input types, fan-out logic, response fields, safety constraints, resolution contract, parent event extraction, news fallback, and cancellation rules. No output schema exists, but the description compensates fully.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The tool description adds significant value beyond the schema by explaining 'quick' vs 'thorough' deployment, what 'include_raw' entails, and providing examples. This elevates it above the baseline of 3.

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

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

The description clearly identifies the tool's purpose: researching a Polymarket bet by pulling relevant Pipeworx data. It uses specific verbs ('Research', 'pulling', 'return') and the resource ('Polymarket bet'). It distinguishes from sibling tools like 'ask_pipeworx' and 'polymarket_arbitrage' by focusing on a single comprehensive research call with fan-out to data packs.

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', 'is there edge in Z'. It does not explicitly state when not to use the tool or mention alternatives, but the given use cases are clear and specific.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds detailed behavioral info: pulls specific financial data from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted results with citation URIs. No contradictions.

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

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

The description is dense but efficient, front-loading purpose with common queries. All sentences add value; no fluff. Slightly lengthy but justified by the amount of useful 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 2 parameters, no output schema, and annotations present, the description fully covers what the tool does, when to use it, what data to expect, and how results are sorted. Completely adequate for agent selection and 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% but description adds significant value: explains enum options with examples (e.g., tickers for company, drug names), clarifies min/max values, and describes what data each type returns. Enhances understanding beyond schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, with example phrases like 'X vs Y' and 'rank these companies'. It distinguishes from sibling tools like entity_profile and sequential lookups.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides context with example query patterns. Clearly indicates when to use this tool (comparisons) without ambiguity.

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

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

The description discloses key behavioral traits beyond annotations: expected 15-60s response time, parallel execution across many tools, returns gaps[] for unanswered facets, and requires authentication. It does not contradict annotations (readOnlyHint, idempotentHint, etc.) and adds context like the structured nature of data sources.

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 relatively long but efficiently structured with front-loaded critical caveats (account requirement, alternative). Every sentence adds essential information for correct tool selection and invocation, though slight trimming could improve conciseness.

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

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

Given the complexity of the tool, the description is exceptionally complete: it explains the output format (findings packet with evidence, confidence, source, citation, gaps), prerequisites, timing, and when to expect empty results. No output schema exists, so the description fully compensates.

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%, providing baseline clarity. The description adds value by explaining that depth='quick' uses 3 facets, 'standard' 5, 'thorough' 8, and that the question parameter accepts broad/multi-part input, going beyond schema names.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and returning evidence with citations. It distinguishes itself from siblings like ask_pipeworx by specifying it is not open-web search and is best for broad/multi-part questions.

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 specifies when to use this tool (broad/multi-part structured data questions) and when not to (single lookup: use ask_pipeworx; breaking news: prefer ask_pipeworx). It also notes the account requirement and that 'thorough' depth needs a paid plan, 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, idempotentHint, destructiveHint. Description adds that results are ready to call with no second schema lookup, which is valuable behavioral context beyond annotations.

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

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

The description is a single paragraph that efficiently covers purpose, usage, and output. It front-loads the key points. Could be slightly more structured, but it's effective and not verbose.

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 discovery tool with no output schema, the description adequately explains what is returned (names, descriptions, schemas, examples) and that it's ready to call. It does not mention edge cases like no results or pagination, but these are acceptable given the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add much meaning beyond the schema's parameter descriptions and aliases. It mentions the query is natural language, but that's already in the schema.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and explains it returns top-N relevant tools with full schemas. It distinguishes from siblings by being a discovery tool for browsing many 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 says 'Call this FIRST when you have many tools available and want to see the option set'. This provides clear when-to-use guidance. Schema examples also aid usage.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds rich behavioral details: fans across multiple sources, returns specific fields, notes USPTO sunset and fallback behavior. Adds context beyond annotations without contradicting them.

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

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

Description is front-loaded with examples and has clear structure. However, it is somewhat verbose enumerating all sources and fields; could be slightly more concise without losing clarity.

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

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

Given no output schema and high complexity (multiple sources, fallbacks, constraints), the description fully covers what the tool returns, its limitations, and how to use it effectively. No 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 for both parameters. Description adds extra nuance: explains value must be ticker or CIK, no names, and references resolve_entity. That's valuable beyond schema, hence above baseline 3.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' and explicitly contrasts it with chaining single-source lookups. Example queries further clarify the purpose. 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack...' and gives a clear when-not-to-use: 'names not supported (use resolve_entity first)'. Provides practical 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 destructiveHint and idempotentHint. Description adds context about clearing sensitive data and deleting stale memories, enhancing transparency 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, no fluff, front-loaded with purpose and usage conditions. Every sentence adds value.

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

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

For a simple tool with one parameter, the description covers purpose, usage, and pairing with related tools. No output schema needed; the description is 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 coverage is 100% and already describes the 'key' parameter as 'Memory key to delete'. Description merely repeats 'by key', adding no new semantics.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key', distinguishing it from siblings 'remember' and 'recall'.

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

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

Provides explicit guidance on when to use: when context is stale, task done, or clearing sensitive data. Also mentions pairing with remember and recall, offering 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 provide readOnlyHint, idempotentHint, and non-destructive nature. The description adds behavioral details (fetches page, extracts title/description/key links, emits markdown) and clarifies output format (single text blob). 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 four sentences long, front-loaded with purpose, then process, then use cases. Each sentence serves a purpose with no unnecessary words. Could be slightly more concise but is efficient.

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

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

Given low complexity, 2 parameters with full schema coverage, and no output schema, the description covers all needed context: purpose, process, output format, and use cases. Annotations fill in safety and idempotence.

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 both parameters are well-described in the schema. The description does not add significant meaning beyond the schema. Baseline score is 3.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt), and process (fetch, extract, emit). It also distinguishes itself from siblings like scan_competitor_ai_presence by focusing on llms.txt generation.

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 (getting client's site indexed, drafting own llms.txt, auditing competitor) and gives context for when to use, but does not mention when not to use or explicitly compare to sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the exact metadata fields returned (license, duration, attribution, source) and clarifying the lookup method (by UUID). No contradiction with annotations.

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

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

The description is two sentences with no extraneous information. It front-loads the purpose and immediately follows with usage guidance, making it 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?

Given the tool has a simple single-parameter schema, comprehensive annotations (readOnly, openWorld, idempotent), and an output schema, the description covers all necessary aspects: what it does, how it works, and when to use it. No missing critical information.

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 description mentions 'by UUID', which aligns with the single 'id' parameter of type string. Although the schema has 0% parameter descriptions, the example in the schema already shows UUID format. The description provides minimal additional meaning beyond the schema example.

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 'Fetch', the resource 'full metadata for a single Openverse audio record', and the method 'by UUID'. It also lists specific metadata fields like license, duration, attribution, and source, distinguishing it from sibling tools like search_audio which returns a list.

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

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

The description explicitly advises to use this tool after 'search_audio' for licensing details, providing a clear workflow context. It does not explicitly state when not to use it, but the single-record usage and UUID requirement imply alternatives for batch operations.

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, non-destructive behavior. Description adds value by disclosing the specific metadata fields returned (license, attribution, source, dimensions). Could mention absence of side effects or error handling but sufficient given annotations.

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

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

Two sentences, front-loaded with action and usage. No filler words; every phrase adds meaning. Optimal length for a simple tool.

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

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

With only one parameter and existing output schema, the description covers core purpose and usage. Could mention that output schema captures return values, but it's complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 0%, so description must compensate. It clarifies the parameter 'id' is a UUID and ties it to an image record. However, it doesn't explicitly state format or validation rules beyond the example. Adds value but could be more precise.

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

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

Description explicitly states 'Fetch full metadata for a single Openverse image record by UUID' and lists returned fields (license, attribution, source, dimensions). It clearly distinguishes from sibling 'search_images' by specifying use case.

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 'Use after `search_images` for licensing details', providing clear context for when to invoke this tool vs searching. No ambiguity about purpose.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context about 'visual-similarity exploration' but does not disclose additional behavioral traits such as pagination, limits, or algorithm details. 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 short, front-loaded with example queries, and contains no unnecessary words or repetition. It efficiently conveys the tool's purpose and usage in a single sentence plus examples.

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

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

For a simple tool with one parameter and an output schema (not shown), the description provides enough context: what it does, when to use it, and the input format. No additional details about return values are needed as the output schema handles that.

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 has 0% description coverage and only one parameter 'id' with no schema description. The tool description mentions 'given Openverse image ID' which clarifies the parameter's role, but this is minimal and does not compensate for the lack of schema-level documentation.

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 concrete user queries ('Find images similar to [X]', 'more images like this') and states it returns related images for a given Openverse ID. It distinguishes from siblings like search_images and get_image by focusing on visual-similarity exploration.

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 and context ('Use for visual-similarity exploration in CC content'). While it does not explicitly state when not to use or name alternatives, the sibling list implies other tools for text-based searches or single image retrieval.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's addition of return fields and include_inactive behavior provides marginal extra context, but 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 concise sentences: first states purpose and output, second gives usage guidance. No redundant information.

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

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

The tool is simple with one optional parameter and no output schema. The description covers return fields and usage, making it complete given the low complexity and thorough annotations.

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

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

The single parameter 'include_inactive' is well-described in the schema (Include cancelled subscriptions, default false). The description does not add meaning beyond the schema, and schema coverage is 100%, so baseline score of 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.), distinguishing it 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?

The description advises using this tool to review active subscriptions before adding more or to find an id to cancel, providing clear context for when to use it.

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

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

Annotations are all false, but description adds crucial behavior: rate-limited to 5 per identifier per day, free, doesn't count against quota. No contradiction with annotations.

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

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

Description is compact (~5 sentences) and front-loaded with core purpose. Every sentence adds value: types, constraints, and tips. 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?

Despite no output schema and nested parameters, the description fully covers how to use the tool, what to include, and behavioral constraints. Complete for an effective feedback tool.

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

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

Schema coverage is 100%, but description enriches each parameter: explains enum values, gives context for optional fields, and specifies message format (plain text, 1-2 sentences, 2000 chars max). Adds significant meaning beyond schema.

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

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

The description clearly states the tool's purpose: sending feedback about broken, missing, or needed tools. It explicitly lists the types (bug, feature, etc.) and distinguishes from sibling tools by being the only feedback mechanism.

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

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

Provides explicit guidance on when to use (bug, feature, data_gap, praise) and what to avoid (pasting end-user prompts). Also mentions rate limits and free usage, helping the agent decide correctly.

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

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

Discloses aggregation, no PII, caching, and purpose beyond annotations. Annotations already indicate read-only, idempotent, non-destructive; description adds valuable detail.

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

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

Two concise, front-loaded sentences with bullet-like enumeration. No wasted words; every sentence adds value.

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

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

Covers purpose, use cases, behavior, caching, and privacy. No output schema needed for a simple aggregation tool; description is fully 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 has 100% coverage with a good description of the window parameter. Description does not add extra information beyond the schema, so baseline of 3 is appropriate.

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

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

Clearly states the tool returns top tools, packs, and call volume from other AI agents on Pipeworx. Distinguishes from siblings like discover_tools and asking 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 lists three use cases with context. Does not state when not to use or compare to alternatives, but provides strong situational guidance.

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

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

Discloses numerous behavioral details beyond annotations: partition check logic, Jaccard similarity filter, placeholder rejection, fill check against live order book, and response structure. Annotations already indicate read-only and idempotent, and description aligns 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 detailed and well-structured with clear sections (modes, semantic anchor, partition filter, fill check), but it is quite long. Every sentence adds value, so it is not overly verbose, but could be slightly trimmed for conciseness without losing important information.

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

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

Given the tool's complexity (multiple modes, internal logic, no output schema), the description is remarkably complete. It explains input options, internal checks, response format, and trading caveats, covering all necessary aspects for correct invocation and understanding.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant context beyond schema, explaining mode switching, expected input formats, and behavior. However, the schema already provides basic semantics, so a slight deduction for redundancy.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (default trending scan, per-event partition check, cross-event topic scan) with specific examples. This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit guidance on when to use each argument: no args for trending scan, `event` for a specific market (recommended), and `topic` for cross-event scanning. It also includes when not to trade (if fill check shows realizable_edge_pp ≤ 0) and references polymarket_fill_risk for custom sizing, indicating 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?

Adds extensive context beyond annotations: model logic (lognormal, GDELT, partition overround, etc.), edge calculation net of slippage, Kelly fractions, filtering steps, and diagnostic output. 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?

Very detailed but well-structured with bold section headers; each sentence adds value. Slightly verbose for the complexity, but appropriate for a technically rich 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?

Fully covers response structure, model details, parameter effects, and diagnostics. No gaps given the complexity and absence of output schema.

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

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

Schema coverage is 100% and description enriches each parameter with default values, usage scenarios, practical examples (e.g., slippage_pp mentions Polymarket fees, min_kelly explains half-Kelly). Exceeds 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?

Clear verb+resource ('scan Polymarket markets, return opportunities') and distinguishes from siblings like 'polymarket_arbitrage' by focusing on Pipeworx disagreement and model-driven opportunities.

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 intended use case ('what should I bet on today'), explains three segments, tradeable-edge knobs, Fed bets handling, and caching policy. Provides comprehensive 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?

The description fully discloses behavioral traits beyond annotations: it reads historical snapshots, computes trends and decay, includes expired opportunities, and notes limitations like the 60-day TTL and intraday vs. close data. This aligns with the readOnlyHint and idempotentHint annotations, with 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 front-loaded with the core purpose, then explains response structure and limitations. It is slightly long but well-organized. A minor trim could improve conciseness 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 fully explains the response fields (tracked[], expired[], snapshot_dates[]) with detailed sub-fields. It also covers limitations and data sources, making it complete for agent decision-making.

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 detailed parameter descriptions. The description adds minimal extra context (e.g., 'snapshot family' for window) but mostly restates schema info (defaults, clamping). Baseline 3 is appropriate as the schema already provides sufficient semantics.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge data.

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

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

The description explicitly explains when to use this tool: to differentiate between a fresh wide edge and a 3-week-old wide edge, implying it should be used when historical persistence matters. It contrasts with sibling tools by focusing on decay and trend, and provides examples of trade implications.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: it walks the ladder, returns detailed fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.), and warns about partial basket fills causing directional risk. No contradiction with annotations.

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

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

The description is comprehensive and well-structured with clear sections and bolded key terms. It is somewhat long but every sentence carries meaning. A slight reduction from perfect because it could be more terse, but the structure compensates.

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 lists all return fields for both modes (top_of_book, vwap_fill_price, shares_filled, verdict, theoretical_sum, per-leg fill detail, thin_legs, etc.) and explains the logic. It also covers edge cases like partial fills and directional risk. Together with the parameters, it provides a full understanding.

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

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

Schema coverage is 100% with descriptions for all 4 parameters, but the description adds significant value: it explains the required mutual exclusivity of market and event, clarifies side default behavior for basket mode (auto from partition sum), and interprets size_usd differently for single-market vs basket (max spend vs target proceeds vs settlement notional).

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market and basket) and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges by stating when to use this tool before acting on signals from those 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?

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when to use single-market vs basket mode and provides a rationale: theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral detail: it compares bet shapes, discloses compatibility_warning conditions (non-equivalent bet shapes or semantically unrelated events), explains temporal_alignment, and describes skipped cross-type/subtype counters. No contradiction with annotations.

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

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

The description is long but well-structured: first sentence defines purpose, then modes, response, safety fields. Every sentence adds value, though some minor redundancy could be trimmed. It earns its length.

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

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

Given no output schema, the description fully explains the response structure (leg-by-leg prices, spread array, compatibility_warning, temporal_alignment). It covers all necessary aspects for the agent to interpret results correctly, including edge cases.

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 value beyond schema by explaining the two modes, listing all topic values, and clarifying that explicit parameters override topic-mapped sides. Examples in schema also help.

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

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

The description clearly states the tool's purpose: cross-venue spread between Kalshi and Polymarket. It specifies two modes (topic shortcuts and explicit events) and explains the output. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on matched questions across venues.

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

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

The description provides explicit guidance on when to use: when bet shapes are equivalent the delta is a real signal, when not the tool says so. It warns that most pre-mapped topics return compatibility warnings, so pre-mapped ≠ tradeable. This helps the agent decide when spreads are meaningful.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context: scoping to identifier, listing all keys when omitted, and pairing with forget for deletion. 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 convey purpose, usage modes, scope, and paired tools with zero redundancy. Every sentence adds unique value.

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

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

Given one optional parameter, clear annotations, and no output schema, the description covers all necessary aspects: what it does, when to use, scope, and related tools.

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

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

The sole optional parameter 'key' is fully described in the schema. The description adds meaning by explaining that omitting the key lists all saved keys, which is not evident from 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 clearly states the tool's purpose: retrieving a saved value or listing all keys, with a specific verb ('Retrieve') and resource ('value saved via remember'). It distinguishes the two modes and indicates scope.

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

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

The description explicitly says when to use the tool ('look up context the agent stored earlier') and pairs it with 'remember' and 'forget' for save/delete. It implies alternatives but does not explicitly state when not to use.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable context about mark_read modifying state for subsequent calls and the return fields, going beyond the annotation information without contradicting it.

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, front-loaded with purpose, and every sentence adds value. No extraneous information.

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

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

Given the tool is read-only with full schema coverage and annotations, the description covers return values (fields), filter options, stateful behavior, and alternative access. No gaps identified.

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 adds meaning by explaining how to use parameters (e.g., example filter type 'sec_8k', effect of mark_read on next call), which helps the agent correctly invoke the tool.

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 begins with a specific verb-resource pair ('Pull fired events from your subscription feed') and clarifies what is returned (source, citation_uri, raw event payload). While it does not explicitly differentiate from sibling tools, the purpose is clear and well-scoped.

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

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

The description mentions that polls work fine and gives an alternative API access, but it does not provide explicit guidance on when to use this tool versus sibling tools like list_subscriptions or recall. Usage context is implied but not comparative.

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 details the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO) and their fallback logic, which is beyond the annotation hints. It also mentions return structure, 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 thorough but front-loaded with example queries. While slightly long, every sentence serves a purpose—detailing sources, fallback, parameters, and alternatives—justifying its length.

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

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

Given the complexity (multiple sources, fallback logic, parameter formats) and lack of output schema, the description covers all essential aspects: purpose, behavior, parameters, return structure, and a sibling alternative. Highly complete.

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

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

Schema coverage is 100% but the description adds clarity: `type` is only 'company', `since` accepts ISO or relative (with examples like '30d', '1m'), and `value` can be ticker or CIK. This enhances usability 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 clearly states the tool provides a 'change feed for a company in the last N days/weeks/months' with specific example queries. It distinguishes from sibling `entity_profile` which returns a static profile, making the purpose 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?

The description explicitly mentions using `entity_profile` instead when the static profile is needed, providing a clear alternative. It implies usage for 'what's new' queries but could be more explicit about when not to use this tool.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds scoping by identifier, persistence details, and session retention (24h). Does not contradict annotations. Overwrite behavior could be clarified, but overall good.

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 (6 sentences), front-loaded with the primary action, and each sentence adds meaningful information without redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema), the description fully covers purpose, usage, persistence, and related tools. No gaps identified.

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 key and value. The description reinforces key-value pair semantics and provides naming examples (e.g., 'subject_property'), adding value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and specifies the resource as key-value storage. It explicitly distinguishes from sibling tools 'recall' and 'forget'.

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

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

Describes when to use ('when you discover something worth carrying forward'), provides concrete examples (ticker, address, preference), and explains persistence behavior (authenticated vs anonymous) and pairing with 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 indicate safe and idempotent. Description adds value by noting internal cascading through multiple lookup endpoints and that it replaces manual lookups. 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?

Description is moderately sized with effective front-loading of example queries. Structured with sections for each entity type. Every sentence adds value, though slightly verbose.

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 two entity types and no output schema, the description fully explains what each call returns (ticker, CIK, company name, citation for company; RxCUI, ingredient, brand for drug). It covers input variations and internal behavior, leaving no obvious 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 has 100% coverage but description adds examples and accepted formats ('ticker, CIK, or name' for company; 'brand or generic name' for drug), enhancing understanding beyond enum and type.

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

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

The description clearly states the tool resolves names to identifiers, with specific examples ('ticker for...', 'CIK for...'). It lists supported entity types (company, drug) and what each returns, distinguishing it from siblings by being the primary identifier resolution tool.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides clear context for when to use, though it doesn't explicitly state when not to use or mention alternatives, but given the tool's unique role, this is adequate.

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 non-destructive behavior. The description adds that the tool probes each entity with ai_visibility_check and returns a ranked list with metrics, providing context beyond 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 concise sentences, front-loaded with the main action, and contains no fluff. Every sentence adds essential information without being verbose.

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 explains the return format (ranked list with score, confidence, signal density). The openWorldHint annotation covers variability. Minor gap: no mention of pagination or limits on entity count, but the schema requires 2-8 entities.

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

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

Schema coverage is 100%, and the description adds value by explaining that entities should be brand/business/product names with the first as subject, and that models can be omitted for default workers-ai. This enhances understanding 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 clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes itself from sibling ai_visibility_check (single entity) and compare_entities (generic) by focusing on AI-marketing audits.

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 specifies the tool is useful for competitive AI-marketing audits and mentions the underlying ai_visibility_check. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or alternatives like compare_entities.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals that the tool fans out to two external services, handles partial failures gracefully with a sources_failed list, and that bundlephobia's first measurement may take 5-30 seconds. No contradictions with annotations.

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

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

The description is well-structured with purpose upfront, then details and caveats. It is slightly verbose but every sentence adds meaningful information. No wasted words.

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

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

Despite no output schema, the description enumerates the return content (summary block, per-advisory detail, links, alternative versions) and explains error handling. This fully equips an agent to understand what the tool returns and how to handle timeouts.

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 description adds context beyond the 100% schema coverage: package parameter accepts scoped npm names (e.g., '@types/node'), and version defaults to latest when omitted. This clarifies 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 defines the tool as a composite check for npm packages, combining deps.dev and bundlephobia data. It uses specific verbs ('fan out', 'return') and distinguishes from any sibling tools that might perform similar package 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 specifies NPM-only scope and directs other ecosystems to an alternative (deps.dev:version directly).

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds that it searches CC-licensed audio and is for legal reuse, which provides useful context. No contradictions with annotations.

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

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

The description is somewhat verbose with repeated phrases like 'royalty-free / Creative Commons / public-domain' and uses quotes and slashes. It front-loads the purpose but could be more concise. Adequate but not streamlined.

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

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

With 6 parameters, 0% schema coverage, and an output schema present, the description covers the tool's purpose and use cases but lacks detailed parameter documentation. It does not explain return values, but the output schema presumably does. Overall adequate but with 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 0%, and the description does not explain parameters individually. It hints at 'filter by license, source' and provides examples with 'query', 'page', 'license', 'license_type', but lacks explicit descriptions for 'page_size' and 'source'. Examples partially compensate but are insufficient.

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 searches for Creative-Commons-licensed audio (music, sound effects, podcast clips) via Openverse, with filtering options. It provides specific search patterns like 'Find royalty-free audio for [X]'. However, it doesn't explicitly differentiate from sibling tools like 'get_audio' or 'audio_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 suggests use cases (video/podcast/game soundtracks needing legal reuse) and mentions filtering by license and source, but does not explicitly state when not to use this tool or contrast it with alternatives like 'get_audio' for retrieving specific files.

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, and idempotent behavior. The description aligns with these by describing a search operation. It adds context about searching multiple repositories via Openverse and filtering capabilities, but does not disclose any limitations or side effects beyond what annotations imply.

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

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

The description is two sentences long, front-loading the purpose. The first sentence is dense but informative, covering examples and capabilities. It is concise enough for an agent to quickly grasp the tool's function.

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 presence of an output schema, the description does not need to explain return values. It covers the main purpose, sources, and filters, making the tool understandable for an AI agent. Minor gaps include lack of pagination details or rate limits, but overall it is 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?

With 71% schema coverage, the schema already describes many parameters. The description reinforces meanings by providing examples (e.g., 'license: cc0,by' and 'size: large') and mentioning commercial-use filtering. This adds practical context, though some parameter details remain schema-dependent.

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 searches for royalty-free/Creative Commons images across multiple open repositories via Openverse. Example queries like 'CC images of [Y]' and 'stock photos of [subject]' make the purpose obvious. It differentiates from siblings such as 'get_image' and 'image_related' by focusing on searching.

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

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

The description provides clear context for when to use the tool, including specific use cases (slides, blog posts, marketing) and filtering options. However, it does not explicitly state when not to use it or compare to alternatives, which slightly reduces 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?

Description discloses key behavior beyond annotations: returns top-N passages with character offsets and similarity scores, uses BGE-base-en embeddings, cosine over 500-char windows, and 200K char cap with truncation flag. Annotations already indicate safe read-only operation.

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

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

Single paragraph is highly efficient, front-loading the main purpose and key details. No unnecessary sentences, every sentence provides essential information.

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

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

Despite no output schema, description effectively explains return format (passages, offsets, similarity scores) and constraints (200K char cap, truncation). Covers all necessary context for agent to use tool 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 description doesn't need to add much, but it provides helpful examples for the 'query' parameter and mentions max chars for 'text', adding value beyond schema.

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

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

Description clearly states 'semantic search INSIDE a fetched record' with specific examples like SEC 10-K body and article. Distinguishes from sibling tool ask_pipeworx_grounded by explaining the pairing usage.

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 ('record too big to cram into the prompt') and provides pairing with ask_pipeworx_grounded for grounded Q&A. Offers clear context on saving context and returning only relevant passages.

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 confirms mutation (creating a subscription), details authentication requirements, notes SMS rate limits (10/day), explains webhook secret return once, and covers delivery channel quirks (auto-disable after 10 failures). No contradictions with annotations.

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

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

The description is well-structured with clear sections for intro, supported types, and delivery channels. It is slightly verbose but every sentence adds necessary detail. Front-loaded with the core purpose.

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

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

Given the complexity (3 params, nested objects, multiple types, no output schema), the description covers prerequisites, type-specific parameters, delivery options, limitations (SMS cap, webhook auto-disable), and return value (subscription ID). It is comprehensive enough 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%, baseline 3. The description adds value by explaining parameter usage per type with concrete examples (e.g., 'items:["5.02"]' for sec_8k, 'topic:"fed"' for polymarket_edge) and adding constraints like phone verification and caps.

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

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

The description clearly states the tool creates a 'proactive monitoring subscription to a live-data event stream' and returns the new subscription ID. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description explicitly mentions prerequisites (Pipeworx OAuth account), supported alert types, and delivery channels. It provides context for when to use but lacks explicit 'when-not' guidance. However, the sibling list and detailed type descriptions imply appropriate usage.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true. The description adds behavioral context: returns static example questions from a live catalog, requires no arguments for full spread, and includes categories. No contradiction with annotations.

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

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

The description is front-loaded with example user intents, then explains what it does and how to use it. Every sentence earns its place; no redundancy. Efficient 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 tool has one optional parameter and no output schema, the description fully explains return value (category-bucketed questions with tool shapes) and usage context. No 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 the 'topic' parameter description already listing all enumeration values and behavior. The description adds the word 'focus' but adds minimal new 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?

The description specifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It clearly distinguishes from siblings like ask_pipeworx and discover_tools by focusing on generating suggestions rather than answering or listing 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?

The description explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do' and advises on when to use topic filtering. It provides clear context for when to call this tool versus alternatives, such as meta-tools.

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

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

The description adds significant behavioral context beyond annotations: it discloses that the row is 'deactivated (not deleted)' and that 'historical events stay available'. This complements the annotations (destructiveHint: false, idempotentHint: true) and provides concrete details about the effect of the operation.

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

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

The description is extremely concise, with two sentences covering purpose, ownership, and effect. No unnecessary words, and all information is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema, low complexity), the description fully covers what the agent needs: what it does, who can use it, and what happens to the data. 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?

The input schema has 100% coverage with a single parameter 'id' documented as 'Subscription id (uuid) returned by subscribe.' The description reiterates 'by id' but adds no new meaning beyond the schema, which is adequate for full coverage. Baseline of 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource ('subscription'). It distinguishes from sibling tools like subscribe and list_subscriptions by specifying the cancellation action with ownership constraints.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear criteria for when the tool is applicable. It also explains the behavioral effect (deactivation, not deletion), aiding usage decisions. However, it does not explicitly mention when not to use it or list 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: returns a verdict with categories (confirmed, refuted, etc.), structured form, actual value with citation, and percent delta. It also discloses the data source limitations (only US public companies). 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 trigger phrases first, then purpose, domain, and technical details. Every sentence adds value, but it could be slightly shortened 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 thoroughly explains return types (verdict, structured form, value, citation, delta) and the tool's efficiency. It covers scope, limitations, and replaces multiple calls, making it fully informative for an agent.

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

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

Schema coverage is 100% (one parameter with description). The description adds examples and clarifies the natural-language nature, which aids interpretation. This adds some value beyond the schema, though not dramatically.

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 natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific domain (company-financial claims via SEC EDGAR + XBRL). It distinguishes from siblings by focusing on fact-checking rather than general search or entity lookup.

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

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

Provides explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies the claim type (company-financial) and notes it replaces multiple sequential calls, implying efficiency. However, it lacks explicit exclusions or alternative tools for non-financial claims.

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