Comicvine

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

Annotations indicate read-only, idempotent, non-destructive. The description adds significant behavioral details: default free model, optional paid Anthropic probing, return structure (score, confidence, signals, raw_response, combined view). 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?

Three sentences, front-loaded with main purpose. Each sentence adds essential information: purpose and output, model options and cost, return format, use cases. 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 4 parameters, no output schema, and no nested objects, the description covers key behaviors and return format. It lacks error handling details (e.g., what if '_apiKey' is missing when 'anthropic' is selected), but overall sufficient for a well-annotated tool.

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

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

Schema coverage is 100% for all 4 parameters. Description adds value beyond schema: explains default model for 'models', BYO key for '_apiKey', and disambiguation hints for 'context'. Provides concrete examples (e.g., 'Pipeworx', 'B2B SaaS').

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: probing LLMs for entity knowledge and scoring visibility (0-100). It specifies the verb 'probe', the resource 'LLMs', and the output format. It distinguishes from sibling tools like 'entity_profile' or 'ask_pipeworx' by focusing on AI visibility scoring.

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

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

The description gives usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use default vs Anthropic models. However, it does not explicitly exclude scenarios or compare to the sibling 'scan_competitor_ai_presence', which could overlap.

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, destructiveHint. Description adds context about routing to many tools, structured answers, citations, and tier compatibility, enhancing transparency.

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

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

The description is front-loaded with purpose and usage, includes examples and alternatives. While lengthy, every sentence adds value with 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 simple question-answering tool with full schema coverage, the description covers input, process, output (citation URIs), and usage boundaries. No critical gaps.

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

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

Schema coverage is 100% with all parameters described as natural language input. Description adds no new per-parameter details beyond schema, but examples illustrate 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 it answers factual questions with structured data, routes to 4774 tools, and returns citation URIs. It distinguishes from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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 'START HERE for most questions', lists question phrases, and gives clear conditions for stepping up to alternatives like ask_pipeworx_grounded or deep_research.

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

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

Adds significant context beyond annotations: describes the extra LLM call cost, the extraction-only behavior, and the structured refusal reasons. No contradiction with annotations (readOnly, openWorld, idempotent, non-destructive).

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

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

Well-structured and front-loaded with key information, but three sentences could be slightly tightened. Each sentence adds value, so it remains 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?

Despite missing output schema, description fully explains the return format on success and failure, including all refusal reason values. Covers cost trade-off and use cases, making it complete for agent decision-making.

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

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

Schema coverage is 100%, and description mostly reiterates the schema's alias list. Does not add 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?

Description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It distinguishes itself from sibling 'ask_pipeworx' by specifying the grounded extraction behavior and 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?

Explicitly states when to use (quoted/cited/acted-on answers, high-stakes domains) and when to prefer the sibling tool (casual lookups). Provides clear context for choosing the right 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 indicate readOnly and idempotent, but the description adds extensive behavioral context: resolver contract with market_match_confidence and suggestions, parent event extraction, news fallback fields, safety mechanisms for low-confidence matches and closed markets, wide spread handling, and cancellation rule parsing. This goes well beyond the annotations.

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

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

The description is very long and densely detailed, with structured sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). While well-organized, it is not concise; it contains many sentences that, though informative, could be condensed without losing essential guidance. The front-loading is good (first sentence captures core purpose), but the length overall reduces 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 (3 parameters, no output schema), the description is exceptionally complete. It covers input resolution, classifier types, fan-out examples per category, full response structure (market, analysis, evidence, resolver contract, parent event, news fields, safety, cancellation rules). Everything an agent needs to understand behavior and return values is present.

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

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

Schema coverage is 100%, so the description adds minimal value beyond what the schema already documents. It reiterates input types and gives examples, but does not introduce new semantic information. The baseline for full schema coverage is 3.

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

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

The description opens with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It explains inputs (slug, URL, question) and outputs (evidence packet + market-vs-model comparison). It distinguishes from sibling tools like polymarket_edges by covering classifier fan-outs and resolution details.

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

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

The description explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context on classifiers and fan-out examples. However, it does not explicitly mention when not to use the tool or list alternative sibling tools for edge calculations or arbitrage, which would elevate it to a 5.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the description's additional restriction to 'fictional comic-book characters only' is useful but not extensive. 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, clear sentence with no redundancy, though slightly more structure (e.g., separating fields from restriction) could improve readability.

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 availability of an output schema and comprehensive annotations, the description adequately covers the tool's purpose and scope, including the specific fields returned and the fictional-only constraint.

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

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

Schema coverage is 0% for the single parameter 'id', but the description mentions 'by ID', adding minimal semantic value. No further details on the ID meaning or format are provided beyond the schema's type.

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

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

The description uses a specific verb structure ('Comic Vine single character detail by ID') and lists multiple specific data fields (real name, aliases, powers, etc.), clearly distinguishing it from sibling tools like 'characters' (list) and 'issue'.

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 fetching a single character by ID, but does not explicitly state when to use this tool versus alternatives (e.g., 'characters' for listing) or provide exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description reinforces this with 'Browse' and adds specific return fields (IDs, names, publishers, deck summaries). No contradictions.

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

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

Two sentences: first states the primary action/resource, second provides key usage details. No wasted words, and the most important information is front-loaded.

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

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

For a tool with 4 parameters and an output schema, the description covers the core filtering and pagination. It omits 'sort' but the output schema likely details return fields. Overall sufficient for typical use.

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

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

Schema coverage is low (25%), but the description explains 'filter' (with example formats) and pagination (limit/offset). However, it does not describe the 'sort' parameter, leaving some ambiguity.

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

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

The description uses a specific verb 'Browse' and a clear resource 'Comic Vine's fictional character directory.' It distinguishes from the sibling 'character' (singular) which likely retrieves a single entity, and 'people' for real persons.

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 filtering and pagination guidance with an example, but does not specify when to avoid using this tool (e.g., for a single character, use 'character'). Context from sibling names implies the distinction but is not stated in the description.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context: proper handling of off-calendar fiscal years, sorting by primary metric, and inclusion of citation URIs, enhancing the annotation 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?

The description is fairly long but every sentence contributes value. It is well-structured: trigger phrases, usage preference, then type details. A slight reduction in length would make it 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's complexity (two entity types, multiple comparisons), the description covers triggers, usage preference, data details per type, sorting behavior, fiscal year handling, and output format (paired data + citations). No output schema, but return values are adequately described.

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

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

Input schema has 100% coverage. The description adds meaning beyond schema by explaining type values (company/drug), providing examples for values (tickers/CIKs for company, drug names), and noting fiscal year handling for company type.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases like 'X vs Y' and distinguishes from sequential lookups by stating it replaces 8-15 individual queries.

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

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

The description explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It gives clear when-to-use guidance, though it does not explicitly list sibling alternatives to avoid (e.g., entity_profile for single entities).

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description explains the tool's parallel decomposition, return format (findings packet with evidence, confidence, source, citations, gaps), behavior when data is unavailable (returns empty gaps), and expected response time (15-60s). 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 detailed but appropriately structured. It front-loads critical info (account requirement, fallback tool) and covers all necessary aspects. While slightly dense, every sentence adds value, and the length is justified by 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?

Given the tool's complexity and lack of output schema, the description thoroughly covers required account, data source count, parallel processing, return format with explicit gaps, time estimate, and comparisons with sibling tools. It leaves no critical gaps for correct usage.

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

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

Input schema has 100% description coverage, so baseline is 3. The description adds meaningful context: it specifies the number of facets for each depth value (quick=3, standard=5, thorough=8) and mentions the paid plan requirement for 'thorough', which goes beyond the schema's simple 'How many facets' description.

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

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

The description clearly states that the tool performs grounded multi-source research across structured data sources using parallel decomposition. It distinguishes itself from siblings like ask_pipeworx by specifying its unique capability for broad/multi-part questions over structured data, and explicitly says it is NOT open-web search.

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

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

The description provides explicit guidance on when to use deep_research versus alternatives: for broad/multi-part structured data questions, while recommending ask_pipeworx for single lookups and breaking news. It also notes account requirements, paid plan needs for depth:'thorough', and a fallback if not signed in.

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=true, idempotentHint=true, destructiveHint=false. The description adds that results are 'ready to call directly, no second schema lookup needed' and include curated examples, which is useful behavioral context beyond the annotations.

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

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

Every sentence adds value: purpose, domains, return format, usage advice. It is front-loaded with the main action and ends with a clear call-to-action. No superfluous content.

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

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

With 6 parameters, full schema coverage, and no output schema, the description adequately describes the return value (top-N tools with schemas and examples). The advice to call first fills the contextual need for tool discovery.

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 6 parameters described. The description further explains that 'query' accepts aliases (task, q, description, search) and provides example values, adding meaning beyond the raw 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: 'Find tools by describing the data or task.' It lists numerous example domains and specifies the return format (top-N relevant tools with full input schemas). This distinguishes it from sibling tools like 'search' or 'entity_profile' which are for specific queries or entities.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. However, it does not explicitly state when not to use it, though the context implies it's for discovery rather than direct answer retrieval.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent. Description adds rich behavioral context: fans out across sources, returns specific fields, notes patent API sunset. No contradiction.

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

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

Description is dense but well-structured with examples and clear sections. Each sentence adds value, though the list of returns could be slightly trimmed without loss. No wasted words.

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

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

Given no output schema, the description comprehensively covers inputs (ticker/CIK) and outputs (filings, fundamentals, patents, news, LEI). Handles edge cases (patents soft-fail, name requirement for resolve_entity). Fully adequate 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 descriptions. The description adds concrete examples ('AAPL', '0000320193') and reinforces that names are unsupported, exceeding schema detail. Enums are also noted.

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

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

The description explicitly states the tool provides a full cross-source profile of a US public company in one parallel call, listing sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and returned data. It distinguishes from siblings by advising preference over chaining single lookups and referencing resolve_entity for names.

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?

Clear when-to-use: for holistic view of a company. Explicit preference over alternatives (chaining single lookups). Provides exclusion: 'names not supported (use resolve_entity first)'. Also notes patents API may soft-fail, setting 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 indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale context, which enhances transparency 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?

Extremely concise: two sentences that front-load purpose and usage. No unnecessary words; every sentence adds value.

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

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

For a simple 1-parameter tool with no output schema, the description fully covers purpose, when to use, and behavioral context. Complete 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 the 'key' parameter described as 'Memory key to delete'. The description does not add extra meaning beyond what the schema provides, so baseline score of 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 'Delete a previously stored memory by key', specifying the action (delete) and resource (memory by key). It distinguishes from sibling tools 'remember' and 'recall' by indicating it's for deletion.

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 context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', providing clear guidance on alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/key links, and emits standard format, which is consistent and provides more detail.

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

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

Two concise sentences: first states core purpose and process, second lists use cases. No fluff, front-loaded.

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

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

Covers input, process, and output format (single text blob). No output schema, but description adequately explains what is returned. Complete for a simple 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?

Both parameters have good schema descriptions (100% coverage). The main description adds context about url being the site URL and max_links default and max, but not beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states it generates a llms.txt file for any URL, explaining the process and output. Distinguishes from siblings by focusing on a specific AI indexing task, and none of the sibling tools appear to do this.

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

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

Explicitly provides use cases: getting a client's site indexed, drafting for own project, auditing competitor. This helps the agent decide when to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a safe profile. The description adds value by listing the return fields (cover date, store date, etc.), which is useful behavioral context beyond the annotations.

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

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

The description is a single, well-structured sentence that delivers key information upfront without unnecessary words. Every part earns its place.

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

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

Given the low complexity (1 required parameter) and existence of an output schema, the description sufficiently covers the tool's purpose and primary return fields. Minor improvements could include mentioning the source (Comic Vine) more prominently, but overall it is complete enough.

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 0% schema description coverage, the description must compensate. It clarifies that 'id' is a comic book issue ID and lists what the tool returns, but does not detail parameter constraints or format. This provides moderate addition over the basic 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?

Clearly states it retrieves a single comic-book issue detail from Comic Vine by ID, listing specific attributes like cover date, issue number, and characters. This differentiates it from sibling tools like 'issues' (plural) and other entity tools like 'character' or 'volume'.

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 fetching a specific issue by ID, and the context of sibling tools like 'issues' suggests it's for single-item lookup. However, it does not explicitly state when not to use it or provide alternatives, leaving some ambiguity.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc., making the tool's non-destructive behavior clear. The description adds that it retrieves a list from Comic Vine and can be filtered, which is consistent but adds little new behavioral insight beyond annotations.

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

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

Description is short and to the point, with no extraneous words. It front-loads the purpose and filter options. Efficient but could be slightly more structured (e.g., list parameters).

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

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

Output schema exists, so return values need not be described. However, the description does not cover all parameter purposes or provide enough context for a tool with 4 parameters and many siblings. It is adequate but not fully complete.

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

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

Schema coverage is only 25% (only 'filter' has a description). The description mentions filtering by volume, store-date, name, which adds context to the filter parameter but does not explain 'sort', 'limit', or 'offset'. Description does not fully compensate for low schema coverage.

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

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

Description clearly states it lists single comic-book issues and mentions filtering by volume, store-date, name. It differentiates from sibling 'issue' (singular) and 'volume' (series-level) by specifying 'single comic-book issues' and 'magazine-level comic data'. However, it could be more explicit about the distinction from 'issue'.

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 explicit guidance on when to use this tool versus siblings like 'issue', 'volume', or 'volumes'. The description implies it's for lists of issues, but doesn't state when not to use it or alternatives. Minimal usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the safety profile is clear. Description adds only 'caller's active subscriptions' context, which is helpful but not substantial 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 concise sentences: first states purpose and output, second gives usage guidance. Zero wasted words.

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

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

Given simple tool with one optional parameter and no output schema, description covers purpose, return fields, and usage. No gaps identified.

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

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

Schema has 100% coverage for the single parameter (include_inactive), so description does not need to add detail. 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?

Description clearly states the tool lists active subscriptions and specifies return fields (id, type, etc.). Distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises use for reviewing before adding more subscriptions or finding an id to cancel, providing clear context for when to invoke.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. Description adds context about browse vs search, filtering, and pagination behavior, which complements annotations without contradiction.

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

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

Two sentences with no wasted words; front-loaded with purpose, then usage guidance and alternatives. 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?

Given the output schema exists, return values are covered. Description fully explains tool scope, filtering, pagination, and exclusions, making it complete 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 low (25%), but description explains filter format ('name:foo,id:1,2') and pagination (limit/offset), adding meaning beyond the schema. Compensates for missing 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?

Clearly states verb 'browse' and resource 'Comic Vine's comic-book creator directory' with specific roles (writers, artists, etc.). Distinguishes from siblings by explicitly excluding general biography searches.

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

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

Explicitly provides when to use (creating directory browsing) and when not to use (actors, general bios) with alternative tools (TMDb, Wikipedia).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety traits. The description adds no extra behavioral context (e.g., error handling, data freshness, rate limits). With annotations present, the description provides minimal added value.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and scope 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?

An output schema exists (not shown), so return value details are not required. However, the description mentions only a subset of potential fields and does not clarify the parameter. For a one-parameter tool, basic context is provided but lacks completeness regarding input and output scope.

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

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

The input schema has one parameter 'id' with 0% description coverage. The description does not explain the parameter's meaning or format (e.g., numeric Comic Vine ID). It only describes output fields, failing to compensate for the schema gap.

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 retrieves details for a single comic-book creator from Comic Vine, listing specific fields like name, country, birth/death, and deck. It differentiates from sibling tools such as 'character' (for comic characters) and 'people' (potentially broader entities).

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

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

The description implies the tool is for individual creator lookups but does not explicitly state when to use it versus alternatives like 'character' or 'people'. No exclusions or when-not guidance is provided, making it adequate but minimal.

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

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

The description discloses rate-limiting (5 per identifier per day), that it's free and doesn't count against quota, and the non-destructive nature of feedback. This adds behavioral context beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false.

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 (5 sentences) and well-structured, front-loading the core purpose and then providing usage guidance. Every sentence adds meaningful information without redundancy.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description fully covers usage, constraints, and context. It explains rate limits and quota, making it complete for an agent to decide and invoke 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?

The input schema already provides detailed descriptions for all parameters (100% coverage). The description adds semantic value by advising to describe issues in terms of Pipeworx tools/packs and not to paste end-user prompts, improving parameter 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's purpose: sending feedback to the Pipeworx team about bugs, features, data gaps, or praise. It distinguishes itself from sibling tools by specifying unique use cases, and no sibling tool overlaps in 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 provides explicit when-to-use scenarios (bug, feature, data_gap, praise) and what not to do (don't paste end-user prompt). It also explains team readership and roadmap impact, giving clear context for 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that data is derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This provides useful behavioral context beyond annotations without contradiction.

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

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

The description is concise, front-loaded with core purpose, and uses bullet points for usage scenarios. Every sentence adds value without redundancy.

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

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

With no output schema, the description sufficiently states return content (top tools, top packs, total call volume). The tool is simple with one parameter and good annotations, making the description complete for the 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 adds extra semantics to the 'window' parameter, explaining the implication of shorter vs longer windows and noting the default. This exceeds the baseline of 3.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('returns') and resource descriptors ('trending data from Pipeworx'), and distinguishes from siblings like ask_pipeworx and search by focusing on aggregated trend 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?

Explicitly lists three use cases (discovering hot data sources, confirming canonical tool, aligning use case) and provides guidance on window selection (shorter for hot right now, longer for steady-state). This clarifies when to use this tool versus 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 (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and non-contradictory. Description adds significant behavioral context: semantic anchor (Jaccard similarity), partition filter (placeholder slugs), fill check logic (realizable edge vs book depth), and response structure. 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 relatively long but well-structured with logical breaks (e.g., SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Front-loaded with purpose and mode distinctions. Every sentence adds value, though a minor reduction in length could be possible.

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 fully compensates by detailing the response shape (opportunities[], partition_check with specific fields), covering all modes, edge cases (placeholder slugs, low similarity pairs), and fill check constraints. Extremely complete for a complex 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 has 100% coverage (2 parameters, event and topic, both described in schema). Description adds valuable meaning: what each parameter does, examples, recommended usage, and explanation of cross-event mode vs single-event mode. 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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with specific use cases, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also provides when-not-to-trade guidance via fill check and references an alternative tool (polymarket_fill_risk) for custom sizing.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: response structure by segment, edge calculation details, caching policy, diagnostic fields, and market movement warnings. No contradictions.

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

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

The description is front-loaded with purpose but very long (multiple paragraphs with technical details). Some sections could be summarized or moved to auxiliary reference without losing clarity.

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

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

Given 9 parameters and no output schema, the description thoroughly covers response structure, segments, diagnostics, caveats, and edge calculation. Fully compensates for missing 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 clear descriptions. The description adds extra context for some parameters (e.g., slippage_pp notes zero fees but bid/ask spread). Baseline 3 plus added value gives 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 it scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage through its focus on edge detection and model families.

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

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

It explicitly states the tool is built for 'what should I bet on today' and describes when to use. However, it does not explicitly contrast with sibling tools or provide 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?

The description goes well beyond annotations by detailing the response structure (tracked, expired, snapshot_dates), explaining that snapshots are written on cache-miss (hence gaps), and noting that decay numbers are from daily closes, not intraday. It also mentions history depth is bounded by a 60-day TTL. All consistent 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 fairly long but front-loaded with the core purpose. Every sentence provides value, explaining the response format and limitations. Could be slightly tighter, but for a complex telemetry tool it is well-structured.

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

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

Given the tool has two optional parameters, full schema coverage, and no output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and behavioral details like snapshot gaps and decay computation. It covers all necessary context 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?

The input schema already describes both parameters with 100% coverage, but the description adds default values (14 days, '1wk') and clarifies the meaning of 'window' as a snapshot family. This adds useful context beyond the schema's basic descriptions.

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

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

The description clearly states the tool provides edge persistence and decay telemetry, answering a specific question about how long an edge has existed and whether it is shrinking. It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical snapshots rather than current 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?

The description explains when to use the tool (to differentiate between fresh and aging edges) and provides context on the difference between a new edge and an old one. However, it does not explicitly state when not to use it or name direct alternatives, though the sibling list provides other options.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it walks the order book ladder, evaluates fills, and returns a verdict. It warns about forced_directional_risk and the danger of partial fills. The description is consistent with annotations and adds value beyond them.

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

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

The description is long (about 10 sentences) but packed with necessary detail due to the tool's complexity (two modes, many return fields). It uses capitalization effectively for keywords and is front-loaded with the core purpose. A slightly more compact structure could improve readability, but the length is justified.

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

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

The description covers all aspects needed: purpose, parameters, modes, return values, when to use, and behavioral warnings. Without an output schema, it fully explains the return structure including verdict, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It is comprehensive 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?

Parameter descriptions in the input schema are present (100% coverage). The description further clarifies the dual-mode interpretation of `market` vs `event`, the `side` defaults and options for both modes, and how `size_usd` is interpreted in basket mode as settlement notional. This adds meaning beyond the schema.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order book depth. It distinguishes between single-market and basket modes, and lists specific return fields such as top_of_book, vwap_fill_price, slippage_pp, etc. The verb 'check' and resource 'edge' are precise, and the differentiation from siblings like polymarket_edges is evident.

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 tells when to use this tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. It explains why with reasoning about thin books and partial basket fills converting arbs into directional positions. This provides clear context and exclusions for 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?

The description goes well beyond annotations to disclose key behaviors: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and dropped leg comparisons (skipped_cross_type/subtype). This provides rich context for safe usage 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?

The description is longer than ideal but front-loads key information and uses clear structure (modes, response, safety fields). While verbose, every sentence adds value except possibly the editorial last sentence.

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 fully explains the response format including leg-by-leg prices, top spreads, and safety fields. It covers all scenarios the tool handles, making it self-contained.

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

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

With 100% schema coverage, the description adds significant meaning by explaining the topic macro shortcuts, explicit overrides, and providing examples. It clarifies the relationship between topic and explicit 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 defines the tool as calculating the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on inter-venue comparison and specifying the two modes (topic shortcuts and explicit pairing).

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

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

The description explains two usage modes (topic and explicit), provides examples, and warns that most pre-mapped topics currently return compatibility warnings. It implies when not to use (when events aren't equivalent) but lacks explicit alternatives for intra-venue or non-compatible cases.

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 as true and destructiveHint as false, covering safety and idempotency. The description adds that it returns publisher IDs and names, but does not disclose additional behavioral traits like rate limits or schema details beyond the annotations.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. 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?

The description explains the return value (IDs and names) and the tool's role in multi-step workflows (filtering other resources). It is generally complete for a browsing tool, but omits details on the 'sort' parameter, which is relevant for 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?

With only 25% schema coverage, the description compensates by explaining that 'filter' works by name, and that 'limit' and 'offset' enable pagination. However, it does not explain that filter can also use IDs or describe the 'sort' parameter, leaving some ambiguity.

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

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

The description uses a specific verb ('Browse') and resource ('the Comic Vine publisher list'), and lists example publishers (Marvel, DC, Image, Dark Horse) to clarify scope. It distinctly addresses publisher browsing, differentiating from sibling tools like character, issue, volume, etc.

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

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

The description states filtering by name and pagination with limit/offset, and explains the returned IDs/names are useful for filtering in other tools. It provides clear usage context but does not explicitly state when not to use or mention alternatives.

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

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

Annotations include readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (per identifier) and note that omitting key lists all keys. Adds value beyond annotations with no contradictions.

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

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

Three sentences, no filler. Front-loaded with purpose, then usage guidelines, then scoping. 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?

Tool is simple with one optional parameter and no output schema. Description covers purpose, usage, scope, and pairing with siblings. Does not specify return format, but acceptable for a retrieval tool.

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

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

Schema coverage is 100% for the single optional key parameter. Description clarifies that omitting key lists all keys, which is already evident from schema (required empty). Slight added value.

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

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

Description clearly states the tool retrieves values saved via remember or lists all saved keys when key is omitted. Distinguishes itself from siblings 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 clear context for when to use this tool (look up stored context without re-deriving). Does not explicitly state when not to use, but implies through pairing with remember/forget. Good guidance overall.

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 state readOnlyHint and idempotentHint; description adds the mark_read side effect (flagging events as read) and that polling works fine. 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?

Four sentences, front-loaded with purpose, then return format, then parameters. Every sentence adds value without redundancy. Highly concise and well-structured.

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

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

Given 5 parameters and no output schema, the description covers the main behavior, return fields, filtering options, side effect, and alternative access. Lacks explicit return format structure but is sufficient 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. Description adds value by giving an example for type (e.g., 'sec_8k') and explaining mark_read behavior, enhancing understanding beyond the schema.

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

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

The description clearly states it 'Pull fired events from your subscription feed' and specifies what each alert carries (source, citation_uri, raw event payload). It distinguishes from siblings like 'list_subscriptions' and 'subscribe' by focusing on events rather than subscription management.

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 explains filtering by type and since, and the mark_read flag behavior. Provides an alternative access method (GET endpoint) for scripts/dashboards. Does not explicitly state when not to use, but context implies it's for reading alerts from the feed.

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 safety traits. The description adds context: fans out to multiple sources, handles rate limits with fallback, and notes USPTO soft-failure. 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 examples and structured logically. Slightly long but 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 explains return format. Covers input, behavior, alternatives, and limitations fully for a 3-param tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for since (ISO date, relative shorthand), explains value (ticker or CIK), and provides usage guidance (use '30d' or '1m').

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, covering SEC filings, news, and patents. It includes query examples and explicitly 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?

The description provides explicit when-to-use examples and a clear alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' It also explains fallback behavior (GDELT→GNews).

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 non-read-only, idempotent, non-destructive. Description adds value by explaining key-value storage scoped by identifier and memory persistence details (authenticated vs. anonymous). 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?

Single paragraph, front-loaded with main purpose. Every sentence adds necessary detail without redundancy.

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

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

For a simple 2-param tool with good annotations, the description fully covers persistence, scoping, and use-case guidance. No gaps remain.

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

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

Schema covers both params with descriptions. Description adds naming conventions (e.g., 'subject_property'), enhancing parameter understanding beyond schema.

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

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

The description clearly states the tool saves data for reuse across conversations/sessions, specifying verb (save), resource (data), and scope. It distinguishes from sibling tools like recall and forget.

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

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

Explicitly advises when to use (discover something worth carrying forward) and pairs with recall/forget. Provides context on authentication and session memory duration.

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 that each call cascades through multiple lookup endpoints internally, replacing 2-3 manual lookups. This adds useful context beyond the annotations without contradiction.

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

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

The description is a single paragraph that is information-dense but not overly long. It is front-loaded with example queries and clear use cases, though it could be slightly more compact without losing clarity.

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

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

Given the tool has two parameters, no output schema, and moderate complexity, the description thoroughly explains both input usage and expected output structure for each type. It also notes internal cascading, making it complete for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100% with both parameters described. The description significantly adds meaning by detailing the return values for each type (ticker+CIK+company_name+citation for company; RxCUI+ingredient+brand+citation for drug) and providing examples, making it clear what the parameters produce.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers with specific examples (ticker, CIK, RxCUI). It distinguishes itself from siblings by positioning it as the first tool to use when needing an ID, and mentions it replaces multiple manual lookups.

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

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

The description clearly advises to use this tool first when a name needs an ID. It lists supported types and what they return, providing sufficient context for when to invoke it, though it does not explicitly state 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 already declare readOnlyHint, idempotentHint, destructiveHint false. The description adds valuable behavioral details: probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, signal density. 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?

Two concise sentences. First sentence states the action (compare, probe, rank, surface). Second sentence provides use case and return format. No wasted words, front-loaded with key information.

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

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

Given the tool has 4 parameters with full schema descriptions and no output schema, the description provides a complete overview: what it does, how it works (probes with ai_visibility_check), return fields (score, confidence, signal density), and use case. Does not detail confidence computation or signal density meaning but is sufficient for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaning by explaining that the first entity in the array is treated as the 'subject' for narrative purposes, and notes the optionality of models and _apiKey. This goes beyond the schema descriptions.

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

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

The description clearly states it compares AI visibility across multiple entities, uses ai_visibility_check internally, and returns a ranked list with scores. It distinguishes from sibling tool ai_visibility_check by emphasizing multi-entity comparison.

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

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

Provides useful context for competitive AI-marketing audits with an example question ('does Claude know about us as well as our competitors?'). Implicitly suggests single entity checks would use ai_visibility_check, but does not explicitly state when not to use this tool or mention alternative siblings like compare_entities.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: partial failures (bundlephobia can time out), graceful degradation, and the sources_failed list. This goes beyond annotations, though does not cover authorization or rate limits.

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

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

The description is well-structured and front-loaded with purpose. It is not overly verbose; each sentence adds value. Could be slightly more concise, but overall 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 no output schema, the description thoroughly explains the return values: summary block with specific fields, per-advisory detail, links, alternative versions, and partial failure handling. This is complete 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 coverage is 100%, so baseline is 3. The description adds practical details: 'Scoped packages (e.g. "@types/node") are accepted' for the package parameter, and 'Defaults to the latest published version when omitted' for version. This adds meaning beyond the schema.

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

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

The description clearly states it is a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'scan' and 'check', and the resource is clearly 'npm package'. While there are no direct siblings with similar names, the description distinguishes this from other tools by its specific focus.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"', providing clear usage context. It also mentions limitations (NPM only in v1, other ecosystems fall under different tool). However, it does not explicitly state when NOT to use, though the context is sufficient.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds no further behavioral traits (e.g., rate limits, auth needs) and does not contradict annotations.

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

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

The description is brief, front-loaded with purpose, and uses a clear list of resource types. The 'NOT for...' exclusion is explicit but could be integrated more fluidly.

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

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

Despite having an output schema, the description lacks guidance on pagination behavior and search exactness. It adequately covers domain and scope but leaves some practical usage details unspecified.

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 only 25%; the description attempts to compensate by listing resource types and implying query is for name search. However, it does not explain page or limit parameters, nor the format of the 'resources' parameter beyond a comma-separated list.

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

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

The description clearly states it searches a comic-book database by name, listing resource types. It distinguishes from unrelated domains (ML/AI, real-world) but does not differentiate from sibling tools like 'character' or 'issue' that may also search the same database.

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 instructions: use only for fictional comic-book entities, and not for ML/AI research (naming arxiv_search_papers as alternative). However, it does not mention alternatives among comic-related siblings for more specific searches.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds specifics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and output details (offsets, similarity scores). This significantly aids agent decision-making 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?

Four sentences, front-loaded with purpose, each sentence adds unique value. No redundancy or fluff.

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

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

No output schema, but the description explains return format (passages with offsets and scores). It discloses technical details (embedding model, window size, char cap). Missing error handling or no-match behavior, but overall 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 coverage is 100% with good parameter descriptions. The description reinforces but does not add new parameter semantics beyond what's in the schema. The behavioral context (offsets, similarity) is not parameter-specific. Adequate but not exceptional.

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

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

The description uses a specific verb-resource pair ('semantic search INSIDE a fetched record') and clearly distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and contrasting with fetching whole records. The scope is well-defined.

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 case: when records are too big for context. It mentions pairing with ask_pipeworx_grounded. However, it does not explicitly exclude alternatives or compare to other sibling tools like search, which would make it a 5.

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

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

The description discloses important behavioral traits: returns subscription ID, requires OAuth, delivery channel limitations (10/day SMS cap, webhook auto-disabled after 10 failures), and the need for phone verification. Annotations indicate mutation and idempotency, and the description aligns with these.

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 moderately concise and front-loaded with the primary action. Every sentence adds value, but the length could be reduced by structuring into bullet points for different subscription types.

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 multiple subscription types and delivery channels, the description is thorough. It covers authentication, type-specific parameters, delivery channel options and limitations, and the return value. No output schema is present, but the return value is clearly stated.

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 significant meaning beyond the schema by providing concrete examples for each subscription type (e.g., sec_8k with items arrays, polymarket_edge with topic parameters) and clarifying delivery channel requirements.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts, which handle listing, removing, or retrieving 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 clear context on when to use the tool for creating subscriptions, including prerequisites like requiring a Pipeworx OAuth account. It details supported types and delivery channels but does not explicitly contrast with sibling tools or state 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 already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: it is an onboarding tool, returns example questions with tool shapes, and can be called with no arguments or with a topic. No contradictions.

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

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

The description is front-loaded with the purpose and examples of input queries. It is slightly verbose but each sentence adds value (purpose, parameter behavior, usage guidance, return format). Could be shortened slightly without losing meaning.

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 only one optional parameter and no output schema, the description fully covers what the tool does, when to use it, what it returns (category-bucketed examples with tool calls), and how to customize with the topic parameter. 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 covers 100% of the single parameter (topic), but description adds meaning beyond the schema by listing possible values (e.g., 'finance', 'pharma') and explaining that omitting it gives a cross-category spread. This helps the agent understand parameter utility.

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 is an onboarding entry point that returns category-bucketed example questions, distinguishing it from siblings like ask_pipeworx or search. It uses specific verbs like 'returns' and 'call' and specifies the resource (Pipeworx capabilities).

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

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

Explicitly instructs to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives like meta-tools (ask_pipeworx, entity_profile). Provides clear context for when to use vs. not use.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds that the row is deactivated (not deleted) and historical events stay available, providing valuable context beyond the annotations. No contradictions.

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

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

Two sentences, clear and front-loaded. Every sentence adds necessary information: purpose, ownership, and behavioral outcome. No fluff.

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

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

For a simple tool with 1 required param and no output schema, the description covers purpose, ownership, and behavioral outcome completely. Annotations provide additional safety hints.

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

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

Schema coverage is 100% with parameter description for 'id'. Description adds minimal value by mentioning that id is returned by subscribe, but this is already implied in the schema.

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

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

Description clearly states 'Cancel a subscription by id.' The verb 'Cancel' and resource 'subscription' are specific, and the method 'by id' is precise. It distinguishes 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?

Ownership enforcement is explicit: 'you can only cancel your own subscriptions.' This provides clear context for when to use. It doesn't explicitly state when not to use or suggest alternatives, but the constraint is well-defined.

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

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

The description adds significant behavioral context beyond annotations: it discloses the data source (SEC EDGAR + XBRL), the possible verdicts (confirmed, approximately_correct, refuted, inconclusive, unsupported), and the inclusion of citations and percent delta. It also notes that it replaces multiple sequential calls, which is a key efficiency trait. 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 front-loaded with key action phrases and examples, and every sentence contributes useful information. It is somewhat long but not verbose; the list of verdicts and the replaced workflow are valuable additions. Minor improvement could be trimming redundant phrases.

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 sufficiently explains the return value (verdict types, citation, delta). It covers the domain, data source, and usage context. It could be slightly more explicit about the structure of the extracted structured form mentioned, but overall it provides good completeness given the tool's simplicity (single input).

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

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

Schema coverage is 100% with a detailed description of the 'claim' parameter including examples and a natural-language description. The description in the tool definition reinforces the expected format and domain, adding value beyond the schema by providing concrete examples and clarifying the claim type (e.g., 'Apple's FY2024 revenue was $400 billion').

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 verifies factual claims against authoritative sources, specifying it handles company-financial claims for public US companies. It provides example queries and explicitly distinguishes itself from alternative workflows by stating it replaces 4–6 sequential calls.

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 whenever the agent needs to check whether something a user said is factually correct' and clearly scopes the domain to company-financial claims. It does not explicitly list when not to use or mention sibling alternatives, but the domain restriction is clear enough for an agent to decide.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context on the specific data returned, which helps the agent understand the output format. No contradictory or additional behavioral details are needed given the annotations cover safety.

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

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

The description is a single sentence with no wasted words. It front-loads the purpose and key information about the resource and returned fields.

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

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

Given the tool has a single required parameter and an output schema (not shown but present), the description adequately covers the purpose and return fields. However, it lacks an explicit explanation of the 'id' parameter's origin or format, which 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 single parameter 'id' is not described in the schema (0% coverage). The description implies by context that 'id' is the Comic Vine volume ID, but does not explicitly state this. The parameter is straightforward, 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 states that the tool retrieves Comic Vine single series/volume details, listing specific fields (name, start year, publisher, issue count, deck description). It distinguishes itself from sibling tools like 'volumes' (plural) and 'issues' by specifying 'single series/volume' and the detail fields.

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

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

The description implies use when needing detailed info on one volume, but does not explicitly state when to use this tool versus alternatives like 'volumes' for listing or 'issues' for issue details. No when-not or usage prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering safety. The description adds that it is a list and supports filtering, which provides some behavioral context beyond structured fields, but does not elaborate on pagination or rate limits.

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

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

The description is concise with two sentences: first defines the resource, second states filtering capability. No redundant information, and the critical definition of 'volume' is front-loaded.

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

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

Given the output schema exists and annotations cover safety, the description is somewhat complete for a listing tool. However, it omits mention of pagination (offset/limit) and sorting, which are available in the schema and relevant for using the tool effectively.

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 low (25%); the description adds meaning for the 'filter' parameter (name and publisher filters) beyond the schema's brief example. However, 'sort', 'limit', and 'offset' lack any description, so the added value is partial.

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

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

The description clearly states the tool lists comic-book series/volumes from Comic Vine, defines the term 'volume', and mentions filtering by name and publisher. It implicitly distinguishes from sibling tools like 'volume' (singular) and 'publishers', but lacks explicit 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 guidance is provided on when to use this tool versus alternatives. The description only mentions capabilities without stating prerequisites, exclusions, or context for selecting this tool over siblings.

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