Mygene Info

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral details: it probes multiple models, returns a score (0-100) with per-model breakdown, and notes that using the Anthropic API key incurs direct costs to the user. This goes beyond what annotations provide.

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

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

The description is four sentences, each serving a distinct purpose: function definition, default/api key behavior, return format, and use cases. It is front-loaded with the core action and concise with no wasted words.

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

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

Despite lacking an output schema, the description fully explains the return structure ('per-model {score, confidence, signals, raw_response} + a combined view') and scoring range (0-100). It covers all necessary context for a 4-parameter tool with 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%, so parameters are documented. The description adds meaning beyond the schema by specifying the default model (Workers AI Llama-3.3-70b free), clarifying that the apiKey is passed directly to Anthropic, and illustrating the 'context' parameter's purpose with examples. This adds significant value for the agent.

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

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

Description clearly states the tool probes LLMs for knowledge about an entity and scores visibility 0-100 per model. It uses specific verbs ('probe', 'score') and specifies the resource ('business / brand / product / topic'). The tool's function is distinct from sibling tools like ask_pipeworx or scan_competitor_ai_presence, which focus on single-answer queries or competitor-specific scanning.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the optional api key. However, it does not explicitly state when not to use this tool or mention alternative tools among siblings, which would elevate the score to 5.

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

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

Annotations already declare readOnly, idempotent, openWorld. The description adds that the tool routes internally across many sources and returns structured citations, which enriches understanding without contradicting annotations.

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

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

Well-structured, front-loaded with the key preference note, then domains, then mechanics. Every sentence adds value, though slightly verbose in listing 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?

Given the tool's complexity (multiple aliases, no output schema), the description covers purpose, usage, and expected behavior adequately. It could specify the response format more, but the mention of citation URIs helps.

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 parameters. The description does not add significant new meaning beyond the schema; it merely restates the natural language usage.

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

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

The description clearly states the tool handles factual questions about current/historical data from structured sources with citations, and contrasts itself with web search. However, it does not differentiate from the sibling tool 'ask_pipeworx_grounded', so it's not a perfect 5.

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' and provides a comprehensive list of domains and example queries. Lacks explicit when-not-to-use or alternatives, but the guidance is strong and contextual.

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, openWorldHint, etc.), the description discloses critical behavioral traits: it extracts answers ONLY from tool results, returns explicit refusal reasons with structured fields, and costs an extra LLM call. 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 moderately long but well-structured and front-loaded with the core purpose and use case. Every sentence provides meaningful information, 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 tool's complexity (routing across thousands of sources, extraction logic, multiple failure modes), the description is comprehensive. It covers the return structure, refusal reasons, and trade-offs vs. the sibling, without requiring an output schema.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description adds no further semantic value beyond stating it accepts natural language questions, so a baseline of 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, specifying verb+resource+scope. It explicitly distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and targeted use cases.

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

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

The description provides explicit when-to-use ('when an answer will be quoted, cited, or acted on') and when-not-to-use ('prefer ask_pipeworx for casual lookups') guidance, along with the cost implication 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, destructiveHint=false. The description adds extensive behavioral details beyond annotations: resolution, classification, fan-out, response shapes, resolver contract, parent_event extractor, news fields, safety mechanisms, cancellation rules. 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 purpose but becomes verbose with exhaustive details (examples, response shapes, resolver contract). While well-structured with clear section headers, it is too lengthy for quick scanning. Could be more concise by condensing examples and edge cases.

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: result.market, result.analysis, result.evidence, resolver contract, parent_event, news fields, safety mechanisms, cancellation rules. Covers edge cases like closed markets, low confidence, wide spreads, and resolution risks comprehensively.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains market input flexibility (slug, URL, question), depth options 'quick' vs 'thorough' with behavior, and include_raw parameter with size implications and use cases. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input formats (slug, URL, question text) and explicitly distinguishes itself from siblings by being a comprehensive one-call research tool, not focused solely on edge calculation like polymarket_edges.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides extensive context on behavioral safety (low-confidence short-circuit, closed market handling) that guides proper 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 already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds: side-by-side comparison in one call, latest 10-K data with off-calendar fiscal year handling, FAERS counts for drugs, results sorted by primary metric, and 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 with useful information and front-loaded with query examples. While it is long, every sentence adds value. Minor improvement could be more structured separation of type-specific details.

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

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

Covers purpose, usage, input, data sources, sorting, and output (paired data + URIs). No output schema, but description explains returns. Could mention error handling or caching, but sufficient for the tool's complexity.

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

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

Schema covers both parameters with enums and descriptions (100% coverage). The description adds context: for 'company' type, specific metrics (revenue, net income, cash, debt) and fiscal year handling; for 'drug' type, FAERS counts, FDA approvals, trial counts. It also clarifies maxItems.

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 natural language queries (e.g., 'Compare X and Y', 'which is bigger') and clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes from siblings like 'entity_profile' (singular) and sequential lookups, and specifies data sources per type.

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 to prefer this over sequential single-pack lookups when comparing entities and notes it replaces 8-15 lookups, providing clear when-to-use guidance. It lacks explicit when-not-to-use but the context is strong.

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

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

Discloses key traits beyond annotations: 'never invented', returns explicit gaps, 'Expect 15-60s', and depth parameter behavior. Annotations already declare safe/idempotent/open-world, and description adds valuable context 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?

Front-loaded with core purpose. Every sentence adds value, though slightly verbose for a concise ideal. No fluff.

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

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

Given no output schema, the description fully explains return structure (findings packet with evidence, confidence, source, citation, gaps). Covers prerequisites, performance, and depth behavior comprehensively.

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

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

Schema description coverage is 100% with both parameters fully documented. The description restates schema info without adding new parameter details, so baseline 3 is appropriate.

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

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

The description states a specific verb-resource combination ('Grounded multi-source research') and details the decomposition, parallel routing, and extraction process. It distinguishes from sibling tool 'ask_pipeworx' by noting 'single lookups' vs. '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?

Explicitly states when to use ('broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'), plus prerequisites (Pipeworx account, paid plan for thorough depth).

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds that results include full input schemas with curated examples, ready to call directly, 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 front-loads the purpose and provides examples. It lists many domains, which adds some length but helps illustrate use cases. Could be slightly more concise.

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

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

Given the tool is straightforward with one required parameter and 100% schema coverage, the description adequately explains output (top-N tools with schemas and examples). No output schema exists, so return values aren't detailed, but that is expected.

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

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

Schema description coverage is 100%, and the description repeats the concept of a natural language query. It does not add significant new meaning beyond what the schema already provides for the parameters.

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

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

The description clearly states the tool finds tools by describing data or task, and differentiates itself by advising to call this FIRST when exploring tool options. It lists specific data domains and explains that it returns ready-to-call results.

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 when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set'. While it does not explicitly state when not to use, the context is clear.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds specifics like patent API sunset and soft-fail behavior, and that names are not supported. 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?

Front-loaded with example queries, but somewhat verbose. Every sentence adds value; minor repetition of 'names not supported'. Still effective.

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

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

Given complexity (multi-source, no output schema), description covers inputs, behavior, returns, limitations, and fallbacks. Fully adequate for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions, but description adds usage context: examples of valid tickers and CIKs, and reiterates name restriction. Adds 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 the tool produces a 'full cross-source profile of a US public company in ONE parallel call', listing specific sources and return items. It distinguishes from siblings like deep_research and resolve_entity.

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

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

Explicitly says to prefer this over chaining individual lookups for holistic views, and directs users to resolve_entity first if only a name is available. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds the action 'Delete' but no additional behavioral traits (e.g., not specifying if deletion is irreversible or scoped). The description is consistent but does not enrich beyond annotations.

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

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

Three sentences: first states action, second provides usage rationale, third relates to siblings. No redundant information, very 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?

For a simple tool with one parameter, no output schema, and good annotations, the description covers purpose, usage context, and relationships completely. 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% for the single 'key' parameter, which already has a clear description. The description mentions 'by key' but does not add new semantic information 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?

Description states 'Delete a previously stored memory by key,' clearly specifying the verb and resource. It distinguishes from siblings by contrasting with 'remember' (store) and 'recall' (retrieve).

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 context is stale, task is done, or to clear sensitive data. It pairs with related tools but does not explicitly state when not to use, which is acceptable for a simple 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context (e.g., authorization needs, data source).

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 sentence, which is concise, but lacks sufficient detail to be helpful. It meets minimal conciseness but sacrifices completeness.

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 3 parameters and annotations, the description is too sparse. It does not explain what 'annotations' entails, how to use optional parameters, or any edge cases. Output schema exists but description still needs to define the tool's core functionality.

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 only 33% (only gene_id is documented). The description does not explain the 'fields' or 'species' parameters, leaving their purpose and valid values unclear. With low coverage, the description fails to compensate.

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

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

The description states 'Annotations for a single gene id.', indicating the verb (retrieve) and resource (gene). However, 'annotations' is vague and does not specify what kind of annotations, nor does it differentiate from potential similar tools in the sibling 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?

No guidance is provided on when to use this tool versus alternatives, or any context for exclusion. The description lacks any usage hints.

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 read-only, idempotent, and non-destructive. The description adds that it fetches the page, extracts title/description/key links, and outputs standard markdown. This is useful 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 two sentences front-loading the purpose, followed by details and a 'Useful for' list. Every sentence adds value; 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?

No output schema exists, but the description explains the output is a text blob ready for site-root/llms.txt. It covers process and format. Missing mention of URL accessibility or limitations, but overall 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?

Schema coverage is 100% with good descriptions for both parameters (url, max_links). The description does not add extra parameter information beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb, resource, and purpose. It distinguishes itself from sibling tools which are unrelated.

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 (client indexing, own project drafting, competitor auditing) but does not mention when not to use or alternatives. The sibling list has no direct competitor, so it's clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description confirms listing active subscriptions but adds no new behavioral traits 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 efficient sentences: first defines purpose, second advises when to use. 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?

Simple tool with one optional boolean parameter. Description lists return fields, and schema covers the parameter. Sufficient for context.

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

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

Schema has 100% coverage for the single parameter. Description does not reiterate or enhance parameter meaning, so baseline 3 applies.

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

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

The description explicitly states 'List the caller's active subscriptions' and enumerates return fields, making the tool's purpose and output crystal clear.

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 actionable guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel', though it does not explicitly exclude other uses or compare with siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which provide clear behavioral transparency. The description adds no new behavioral context but does not contradict the annotations.

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

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

The description is extremely concise at just two words, with no fluff. However, it could be slightly more descriptive without sacrificing brevity. Every word earns its place, but the information conveyed is minimal.

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

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

Given the tool has no parameters, rich annotations, and an output schema, the description is minimally adequate. However, it does not fully explain what 'metadata' entails, leaving the agent to infer from the output schema or tool name. A slightly more descriptive sentence would improve completeness.

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?

There are zero parameters, so schema description coverage is 100%. According to guidelines, baseline is 3 with high coverage. The description 'Release / source metadata' adds minimal semantic value beyond the schema and output schema, which likely define the return structure.

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 'Release / source metadata' indicates the tool returns metadata about releases or sources, which is slightly more specific than the name 'metadata' alone. However, it lacks detail on what type of metadata and does not distinguish from sibling tools like 'entity_profile' or 'taxonomy'.

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 no guidance on when to use this tool versus alternatives. There is no context on prerequisites, typical use cases, or when not to use it.

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

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

Annotations provide no behavioral hints (all false). The description adds transparency about rate limits (5 per identifier per day) and quota (free, not counted against tool-call quota), which are critical for an agent to plan usage. 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 dense with information but well-structured: first sentence states purpose, then use cases, then constraints. It could be slightly more concise, but the front-loading is effective.

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

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

Given the tool's simplicity (3 params, no output schema) and richness of annotations, the description covers all necessary aspects: purpose, usage guidelines, rate limits, message formatting, and context relevance. It leaves no gaps for an agent to misuse the tool.

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

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

Input schema covers all 3 parameters with 100% description coverage. The description adds minor context (e.g., message length, context purpose) but most meaning is already in the schema. The description does not add significant new semantics 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: sending feedback about broken, missing, or needed features. It lists specific types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, none of which serve a feedback function.

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

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

The description explicitly specifies when to use the tool: for bugs, feature requests, data gaps, or praise. It also advises against including the end-user's prompt, providing clear do's and don'ts.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds valuable context: data is aggregated from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This goes beyond what annotations provide.

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

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

The description is concise (three sentences plus bullet points), with no wasted words. It front-loads the core function and uses clear structure for usage cases.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains the return content (top tools, packs, volume), caching, data source, and privacy, leaving no significant gaps 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?

The schema already describes the 'window' parameter with enum and description. The tool's description adds semantic guidance (shorter windows for hot topics, longer for steady-state demand, default 24h) that helps the agent choose appropriately.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a window. It uses specific verbs and resource references, distinguishing it from siblings like 'discover_tools' and 'ask_pipeworx' by focusing on trending/aggregate 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?

Three explicit use cases are provided (discovering hot data, confirming canonical tool, aligning use case). While it does not explicitly exclude alternatives, the use cases give clear context for when to invoke the 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 indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond these, detailing the algorithmic checks (monotonicity, partition sum, Jaccard similarity threshold, placeholder filtering, fill check against live order book). It explains edge cases like realizable_edge_pp <= 0 meaning do not trade. 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 relatively long and packed with detail. While every sentence adds value, it could be slightly more concise. However, it is well-structured with clear sections and front-loaded requirements. Still, a 3 is appropriate for a somewhat verbose but informative description.

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

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

Given the complexity of the tool (two modes, multiple checks, no output schema), the description is remarkably complete. It explains the response structure, fill check, and references the sibling tool `polymarket_fill_risk` for custom sizing. The agent can fully understand how to use and interpret results.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by providing example inputs for both parameters (event slugs, topic seed questions) and clarifying that full URLs are accepted for `event`. It also reinforces the mutual exclusivity constraint. This extra context merits a 4.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes between event (single-event) and topic (cross-event) modes, providing specific examples. This is a specific verb+resource pair with clear differentiation between modes.

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 begins with a requirement that exactly one of `event` or `topic` must be provided, and explains the recommended use case for each. It provides detailed context for when to use each mode and mentions additional filters (semantic anchor, partition filter). However, it does not explicitly contrast with sibling tools like `polymarket_edges`.

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

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

The description goes far beyond annotations (readOnly, openWorld, idempotent) by detailing output structure (by_segment with three categories), diagnostic information (_diagnostics with funnel counters), caching behavior (1h KV cache keyed on all knobs), and per-opportunity fields including edge_pp_net, kelly_fraction, and a 24h-move warning. It also explains how tradeable-edge knobs affect filtering.

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

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

The description is lengthy but well-structured, front-loading the core purpose and then systematically covering model families, output fields, and knobs. Every sentence adds information, but the dense prose could benefit from more explicit headings or lists to improve scannability.

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

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

Despite no output schema and few annotations, the description is remarkably complete. It explains all output sections (by_segment, fed_candidates, _diagnostics), return fields for each opportunity, caching policy, and diagnostic information. It covers edge cases (Fed bets unreliability) and provides reasoning for defaults. This fully compensates for missing structured output documentation.

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

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

With 100% schema coverage, the baseline is 3. The tool description adds value by explaining the rationale behind knobs like max_spread_pp ('set to 2 to require tight books') and min_partition_leg_kelly ('use to suppress thin partitions'). These usage tips and scenarios enhance understanding beyond the schema descriptions.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by detailing three distinct model families (model_driven, structural_arbitrage, concentrated_longshot) that produce edge opportunities based on proprietary algorithms.

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 usage: discovering betting opportunities without paging hundreds of markets. It mentions tradeable-edge knobs for filtering but does not explicitly compare to sibling tools or state when not to use it. The built-for purpose is well-articulated, but absence of alternative exclusions prevents a 5.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already declare safety. The description adds significant context: explains response structure (tracked, expired, snapshot_dates), data computation (decay from daily closes, not intraday), and limitations (history depth bounded by 60-day TTL, gaps from cache misses). 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 informative but somewhat lengthy. It is well-structured: first sentence states purpose, then details args and response with clear sections (RESPONSE, LIMITS). Every sentence adds value, though it could be slightly more compact. A solid 4.

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

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

With no output schema, the description fully explains return values (tracked[], expired[], snapshot_dates[]) and their fields, covers limitations, and notes data source behavior. Given the tool's 2 optional parameters, it is completely adequate.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates parameter defaults (days default 14, window default '1wk') and gives a brief qualitative explanation (window family), but does not add new meaning beyond the schema's descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It details the response structure (tracked, expired, snapshot_dates) and explicitly contrasts with the raw polymarket_edges tool by focusing on historical time-series.

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

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

The description implies usage for historical edge analysis but does not explicitly state when to use this tool vs sibling tools like polymarket_edges. It mentions limits (60-day TTL, snapshot gaps) but lacks clear when-to/not-to-use guidance or alternatives.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context beyond this, such as returning a verdict (clean|degraded|cannot_fill), warning about partial basket fills converting arbs into directional positions, and explaining the realizable vs theoretical check.

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 with sections for single-market and basket modes, using bold for key terms. Every sentence adds necessary context; no fluff. Slightly dense but justified given the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and risk warnings. It covers both modes, parameter interpretations, and edge cases, making it complete for an AI agent to use correctly.

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

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

Schema coverage is 100% (all 4 parameters have descriptions). The description adds meaning beyond the schema, e.g., 'size_usd' in basket mode is 'settlement notional S — shares per leg', and side default is 'auto' based on partition sum. This helps an agent understand parameter semantics in different modes.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and lists specific outputs, making it distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also warns against using it when not needed, explaining risks of partial fills and unhedged positions.

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

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

The description goes beyond annotations by explaining safety fields (compatibility_warning, temporal_alignment, skipped_cross_type) and their significance. It discloses that matched pairs can be invalid due to shape or temporal gaps. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 well-structured, starting with purpose, then modes, response, and safety fields. Every sentence adds value, though minor redundancy exists (e.g., 'pre-mapped ≠ tradeable' is already implied). For the complexity, it is concise enough.

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

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

Despite no output schema, the description thoroughly explains the response structure (leg prices, spread delta, compatibility fields) and edge cases (temporal alignment, skipped comparisons). It covers all necessary context for an agent to interpret results correctly.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds significant value by listing topic shortcuts, explaining the two modes, and how explicit parameters override topics. Examples are provided, making parameter usage clear.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts and explicit tickers) and provides context about when spreads are meaningful, differentiating it from related tools like polymarket_arbitrage.

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 includes explicit guidance on when to use the tool (e.g., for arbitrage between venues) and when not (e.g., when compatibility warnings indicate non-equivalent bet shapes or temporal misalignment). It also cautions that pre-mapped topics often yield warnings, setting realistic expectations.

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

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

Annotations already convey readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the description bears little burden. It does not add behavioral context (e.g., performance, rate limits) beyond what annotations provide, earning an average score.

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 (3 words) but at the expense of useful information. It is under-specified for a tool with 5 parameters and many siblings. Conciseness should not sacrifice clarity; this is too minimal.

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 (5 parameters, output schema, many siblings), the description is incomplete. It lacks context on how full-text querying works, example use cases, and integration with other tools. The schema's examples partially compensate, but the description itself fails to provide a complete picture.

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 80%, so the schema documents most parameters. The description adds no parameter-level meaning beyond the schema's property descriptions. Baseline 3 is appropriate; no extra value provided.

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 'Full-text gene query' clearly states the tool's action (query) and target (genes). It effectively distinguishes from sibling tools like 'gene' (likely a different operation) and 'query_many' (batch query) by specifying full-text search on gene data. However, it lacks further detail about scope or special features.

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?

No usage guidelines are provided. The description does not indicate when to use this tool over alternatives like 'search_within' or 'query_many', nor does it mention prerequisites or contexts. Without guidance, the agent must infer usage from the name alone.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing a safety profile. The description adds only 'POST', which is implicit from HTTP method but not contradictory. It does not disclose additional behavioral traits such as response format, error handling, or rate limits, but given annotation coverage, a score of 3 is reasonable.

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 (two words plus method), but it is too minimal to be fully functional. While brevity is positive, the description sacrifices necessary detail, making it barely adequate.

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 4 parameters, an output schema, and annotations, the description does not provide sufficient context. It fails to explain what 'batch lookup' entails, how to construct requests, or interpret results, leaving the agent with significant gaps.

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

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

Schema description coverage is only 25% (only 'scopes' has a description). The tool description adds no parameter-level information. For the three undocumented parameters (ids, fields, species), the description provides no semantic meaning, requiring the agent to infer 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 states 'Batch lookup (POST)', clearly indicating the tool performs a batch retrieval operation via POST. However, it does not distinguish it from the sibling 'query' tool, which likely does single lookup. The verb-resource pairing is clear but could benefit from differentiation.

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?

No guidelines on when to use this tool versus alternatives like 'query' or other related tools. The description lacks any context about appropriate use cases, prerequisites, or scenarios where it should be avoided.

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 behavior beyond annotations: key omission lists all keys, scoping to identifier, and pairing with remember/forget. 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?

Three concise sentences front-loading core function, usage, and context. No unnecessary words.

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

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

Given simple tool with one optional parameter, strong annotations, and no output schema, the description fully covers purpose, behavior, and usage context.

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 repeats the schema's explanation about omitting key to list all. Adds context but no new parameter semantics 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 retrieves a saved value or lists all keys, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Provides explicit use case (look up stored context) and pairing with remember/forget, but does not explicitly state when not to use it compared to other tools.

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

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

Annotations already indicate read-only, idempotent, open-world, non-destructive. The description adds specific behavioral details: returns latest alerts, each with source/citation_uri/payload, explains mark_read effect on future calls, and mentions polling suitability. 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 concise: first sentence states core purpose, second details return fields, then filter options, mark_read behavior, and alternative access. Every sentence adds value; no redundancy.

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

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

For a read tool with no output schema, description explains return fields adequately. Covers all parameters and adds usage context. Minor omission: not explicitly stating ordering (most recent first) or that limit applies to ordering. Still quite 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 description adds significant meaning: explains 'type' with example ('sec_8k'), specifies 'since' requires ISO timestamp, clarifies 'mark_read' and 'unread_only' behavior. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, returns recent alerts with source, citation_uri, and raw payload. This distinguishes it from sibling tools like list_subscriptions or subscribe which manage subscriptions rather than read alerts.

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 usage guidance: mentions polling is acceptable, notes an alternative API endpoint for scripts/dashboards, and implies usage context (reading alerts). However, it does not explicitly state when not to use this tool versus alternatives like list_subscriptions or search_within.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds details: fans out to three sources, fallback logic, soft-fail for patents, and return structure.

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 but well-structured: starts with examples, explains operation, fallback, parameters, return, and sibling differentiation. No fluff.

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

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

No output schema, but description explains return structure (changes[] grouped by source + total_changes + URIs). Covers all three data sources and limitations.

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% for all 3 parameters. Description adds value by explaining date formats (ISO or relative), relative shorthand examples, and value as ticker or CIK.

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' covering SEC filings, news, and patents. It distinguishes from sibling tool 'entity_profile'.

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

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

Provides explicit example queries and recommends 'entity_profile' for static profiles. Does not explicitly state when not to use, but context is clear.

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

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

Description adds value beyond annotations: it clarifies persistence behavior (authenticated users vs anonymous sessions) and scoping by identifier. Annotations show idempotentHint=true and destructiveHint=false, and description aligns with these 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?

Four sentences, front-loaded with purpose, no filler. Every sentence adds value—usage guidance, persistence details, and tool pairing.

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

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

For a simple 2-parameter tool with no output schema and no nested objects, the description covers persistence, scoping, and usage flow. It could mention expected return behavior (e.g., success confirmation).

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 good descriptions for key and value. The description adds context (examples like 'subject_property', 'target_ticker') and mentions key-value pair structure, but doesn't fundamentally extend schema meaning.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference). It distinguishes from siblings recall and forget, which are mentioned explicitly.

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

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

The description provides clear when-to-use guidance: 'when you discover something worth carrying forward' and mentions pairing with recall and forget for retrieval/deletion. However, it lacks explicit when-not-to-use scenarios or alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: each call cascades through several lookup endpoints internally, returns specific citation URIs, and auto-disambiguates for 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 a single paragraph that is reasonably concise and front-loaded with example queries. It contains no filler, but the lack of bullet points or structed sections slightly reduces readability. 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 lookup tool with no output schema, the description adequately explains return values for both entity types. It covers the main use cases. However, it does not mention error handling or behavior when an entity is not found, which is a minor gap for a tool intended as a first step.

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 meaning beyond the schema by explaining how each type interprets the 'value' parameter (e.g., ticker, CIK, or name for company; brand or generic for drug) and what is returned. This clarifies usage beyond the schema's brief descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers with specific verbs like 'resolve' and 'look up'. It provides example queries and details for each supported type. It distinguishes itself from sibling tools by positioning itself as the first step for obtaining IDs needed by 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?

The description explicitly says 'Use FIRST whenever you have a name but need an ID', which gives clear usage context. It explains supported types and what they return. However, it does not explicitly state when not to use or list alternatives, though the context is clear enough.

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

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

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: it performs multiple probes, ranks by score, and returns a ranked list. It also explains that the Anthropic API is called when 'anthropic' is in models, requiring an API key. This provides useful 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 concise (4 sentences) with a clear front-loaded statement of purpose. Every sentence provides value, and there is no redundant or extraneous information. The structure is logical: purpose, method, use case, output format.

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 (4 parameters, no output schema), the description is complete. It explains the internal workflow (probes each entity, ranks scores) and explicitly states the return format (ranked list with score, confidence, signal density). No additional context is needed for an agent to use the 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 baseline is 3. The description adds significant meaning: the first entity is treated as the 'subject' for narrative, and the context parameter disambiguates common names. These details enhance the schema descriptions, making the parameters more intuitive.

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 that the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and identifies the most/least recognized. The verb 'Compare' and resource 'AI visibility across multiple entities' are clear, and it distinguishes itself from sibling tools like ai_visibility_check (single entity).

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

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

The description provides a clear usage context: 'Useful for competitive AI-marketing audits: does Claude know about us as well as our competitors?' This implies when to use (comparative analysis) and implicitly suggests using ai_visibility_check for single-entity queries. However, it does not explicitly list alternative tools or when-not-to-use scenarios, so a 4 is appropriate.

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, idempotent, non-destructive behavior. The description adds value by detailing the composite nature, return fields, failure modes (bundlephobia timeout), and ecosystem scope. 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 a single paragraph but front-loaded with the main purpose. All information is relevant and no redundant sentences. Could be slightly more structured, but overall concise.

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

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

No output schema is provided, but the description thoroughly lists return fields (summary block, advisories, links, alternative versions) and covers failure modes, making it complete for agent 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 both parameters described. The description adds context: default version behavior and acceptance of scoped packages, which goes beyond the schema.

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

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

The description clearly states it's a composite check for npm packages using deps.dev and bundlephobia, with specific verbs like 'scan' and 'fans out'. It distinguishes from siblings by explicitly limiting to NPM ecosystem and directing other ecosystems to alternative 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 states when to use: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also advises against using for non-NPM ecosystems and suggests direct deps.dev usage instead. Mentions partial failure handling.

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

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

Annotations already declare readOnly, openWorld, idempotent. The description adds significant behavioral details: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)' and 'every passage carries an offset so the agent can verify a verbatim quote'. This perfectly complements the annotations with implementation and constraint information.

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

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

Four sentences, all substantive. The first sentence immediately states the core action. The second explains the use case and output. The third connects to a sibling. The fourth provides technical details. No irrelevant information; every sentence earns its place. Front-loaded and efficient.

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

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

Despite no output schema, the description states precisely what is returned: 'top-N passages with character offsets and similarity scores'. It covers constraints (200K char cap, truncation flag), behavioral details (embedding model, window size), and the pairing pattern with a sibling. For a tool with 3 parameters and semantic search complexity, this is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema by explaining how parameters are used together (e.g., 'Pass the text you already pulled... plus a natural-language query'), and provides examples for the query parameter. However, the schema already describes the max chars for text and default for limit. The description adds value but 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 name and title immediately indicate semantic search within a previously fetched record. The description specifies 'semantic search INSIDE a fetched record' and explicitly contrasts with sibling 'ask_pipeworx_grounded', stating they pair together. This clearly distinguishes the tool's purpose and resource.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context'. It also provides a clear alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives both usage context and name-drops a sibling for complementary 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?

Beyond annotations (readOnly=false, idempotent=true), the description discloses important behaviors: returns new subscription ID, webhook secret returned once, webhook auto-disabled after 10 failures, SMS cap of 10/day, and phone verification requirement. No contradictions with annotations.

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

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

The description is well-structured and front-loaded: first sentence states purpose, followed by account requirement, type list, and delivery channels. Every sentence adds necessary information without redundancy. Length is justified by tool complexity.

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

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

Given the tool's complexity (3 params, nested objects) and absence of output schema, the description adequately covers return value (new subscription ID, webhook secret once), prerequisites, and failure scenarios (auto-disabled webhook). Slightly more detail on response structure for non-webhook deliveries would improve completeness.

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 significant meaning beyond the input schema: detailed examples for each type's params, explanations of delivery semantics (e.g., 'must match verified phone', 'signing secret returned once'). While the schema covers 100% of parameters, the description enriches understanding.

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

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

The description clearly states the tool creates a subscription to a live-data event stream and returns an ID. It uses specific verbs ('Create', 'Returns') and distinguishes itself from sibling tools (e.g., list_subscriptions, unsubscribe) by focusing on creation.

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

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

The description provides explicit context: requires Pipeworx OAuth account, lists supported types with examples, and details delivery options. It implies when to use (setting up monitoring) and mentions a limitation (anonymous/BYO cannot persist). While not explicitly contrasting siblings, the context is comprehensive.

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, and non-destructive. The description adds that it returns category-bucketed examples with tool+argument shape, drawn from a live catalog. No contradiction; the description enriches the behavioral understanding.

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

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

Description is detailed but well-structured, front-loading trigger phrases and key information. It efficiently packs multiple pieces of context without being overly 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 no output schema, the description explains the return format comprehensively. It covers multiple use cases, parameter handling, and relationship to other tools, making it complete for an onboarding tool with 1 optional parameter.

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

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

Schema covers the optional topic parameter with clear description. The description adds context on possible values and behavior with/without the parameter, enhancing meaning 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 that the tool returns category-bucketed example questions with exact tool arguments, serving as an onboarding entry point. It distinguishes itself from siblings like ask_pipeworx and discover_tools by focusing on providing example questions rather than answering queries directly.

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

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

Explicitly advises using this tool first when the agent doesn't know what Pipeworx can do, and provides guidance on focusing by topic. It tells when to use vs. alternatives, making it clear that this is for orientation.

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 and idempotentHint as true, indicating safe, read-only behavior. The description adds no additional behavioral context (e.g., what happens if the species is not found, any caching, or data coverage), providing minimal value beyond what annotations convey.

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 short (3 words), which is concise but at the expense of usefulness. It lacks structure and does not prioritize key information, making it insufficient for an agent to understand the tool's 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?

Although the tool has an output schema (reducing the need to explain return values), the description fails to provide enough context about the tool's scope, source of data, or how it handles input variations. Given the simplicity of the tool, the description is incomplete.

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 parameter 'species' has no description in the schema (0% coverage), and the description does not explain what values are acceptable (e.g., common names, scientific names, IDs, or taxonomy IDs). The examples in the schema offer some context, but the description itself fails to add semantic meaning.

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

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

The description 'Species taxonomy info.' is vague, only indicating that the tool provides taxonomy information about species. It lacks specificity about the type of taxonomy data (e.g., classification, synonyms, hierarchy) and does not differentiate from sibling tools like 'entity_profile' or 'gene'.

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?

No usage guidelines are provided. The description does not explain when to use this tool over alternatives, nor does it specify prerequisites or context, leaving the agent without guidance on appropriate invocation.

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

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

The description adds behavioral context beyond annotations: ownership enforcement and deactivation behavior. It aligns with annotations (destructiveHint=false, idempotentHint=true) and explains the side effects 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, each adding essential information: purpose, ownership constraint, and behavioral detail. No unnecessary words.

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

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

For a simple mutation tool with one required parameter and no output schema, the description fully covers purpose, usage constraints, and behavioral effects. It even references the sibling 'recent_alerts' for historical context.

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 for the single parameter 'id', with a clear description. The tool description adds no additional parameter details, but the schema already suffices. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It also explains ownership enforcement and deactivation behavior, which distinguishes it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly notes ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion), providing clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternative 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 declare safe, idempotent, read-only behavior. Description adds return value details (verdict categories, citation, delta) and v1 limitation. 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 purpose and is efficient, though slightly verbose with bullet-like list. 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?

Despite no output schema, description thoroughly covers input format, output types, domain, and limitations. Fully adequate for the tool's complexity.

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

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

Single parameter 'claim' with schema description. Description adds example claims and explains the output structure, adding context 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?

Description clearly states the tool verifies natural-language claims against authoritative sources, specifically company-financial claims. Provides example queries and explains the integrated nature, differentiating it from sequential alternatives.

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 whenever the agent needs to check factual correctness.' Specifies domain (company-financial for US public companies). Lacks explicit when-not-to-use or alternative sibling 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.