Comicvine

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

Annotations already declare readOnly, openWorld, and idempotent. Description adds critical context: external API calls to Anthropic require user-provided key and incur costs, and return format includes per-model details. 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 purpose, no unnecessary words. Efficiently conveys what, why, and how.

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

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

Covers purpose, parameters, and return structure despite no output schema. Lacks error handling or rate limit info, but sufficient for a probe tool with strong annotations.

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

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

All 4 parameters are described in the schema (100% coverage). The description adds examples and clarifies the entity parameter type and the optional context parameter's purpose, providing marginal 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?

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility from 0-100. It distinguishes from siblings by focusing on AI visibility measurement rather than general queries or other specific functions.

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

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

Description explains typical use cases (AI-marketing audits, pre-launch brand checks) and model selection (default workers-ai, optional anthropic with key). However, it does not explicitly differentiate from similar siblings like 'scan_competitor_ai_presence'.

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 only state readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantive behavioral context beyond annotations: it routs to other tools, fills arguments, returns structured answers with citation URIs, is fast ('one fast call'), and works on every tier. It also notes that breaking news is routed to live news feeds. 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 long but every sentence carries useful guidance, from the bold 'PREFER OVER WEB SEARCH' opener to the clear sibling differentiation and examples. It is front-loaded with the primary directive and structured logically. Slightly verbose but not wasteful; earns a 4.

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

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

With no output schema, the description explains the return format ('structured answer with stable pipeworx:// citation URIs') and explicitly describes the tool's breadth (5,529 tools, 1455 sources). It covers when to use, when to step up to alternatives, and what types of questions to ask. This is complete for a broad fact-finding 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 description covers 100% of parameters, with 'question' fully described and five aliases listed. The description adds no new parameter semantics but provides usage examples (e.g., 'current US unemployment rate') that reinforce the natural-language nature. Since schema coverage is high, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's role: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This specifies a unique verb+resource and distinguishes it from siblings by explicitly naming alternatives 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?

The description is explicit about when to use it: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'START HERE for most questions.' It also provides exclusions and alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is textbook usage guidance.

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

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

It discloses critical behavioral traits: candidate routing improvements may be enabled live, currently no active candidate making it identical to ask_pipeworx, and it is a full working router not a fallback. This complements the readOnly/idempotent annotations by explaining variability over time and the evaluation context.

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

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

Three sentences with clear structure: definition, current status, and usage instruction. It is slightly longer than strictly necessary but every sentence carries useful information and it is well 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?

The description thoroughly covers the tool's purpose, relationship to ask_pipeworx, current behavior, and usage guidance. Since there is no output schema, it could mention return value shape or potential latency/limitations, but for a query router this is sufficient.

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

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

The input schema has 100% coverage with descriptive parameter entries including the main 'question' field and its aliases. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate given the schema already does the heavy lifting.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router with 5,529 tools, and differentiates itself from the stable sibling by experimental routing improvements. It provides a specific verb and resource, making the purpose unambiguous.

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

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

The description explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router to decide what merges. It implies the alternative (stable router) for non-experimental use, though it does not spell out 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?

Beyond the readOnly/idempotent annotations, the description reveals critical behavioral traits: it returns an explicit refusal with specific reasons when data is insufficient, includes evidence (verbatim quote), and costs an extra LLM call. It also states it uses 'ONLY what the tool result contains.' No contradiction with annotations is present.

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?

Although detailed, every sentence earns its place: purpose, routing mechanism, return format, refusal reasons, usage context, and cost trade-off. The description is front-loaded with the key purpose and efficiently structured, making it dense but not verbose.

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

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

The tool has no output schema, but the description fully specifies the success return object and all refusal reason enum values. It also provides context on the 5,529 tools and 1455 sources, and the cost comparison to ask_pipeworx, making the description complete for an agent to use this 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 schema description coverage is 100%, clearly defining the 'question' parameter and its aliases. The tool description does not add further parameter-specific semantics or examples, so it relies on the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains its unique behavior: it routes through the same tool selection as ask_pipeworx but extracts answers using only the retrieved result. This distinguishes it from sibling tools like ask_pipeworx and makes the purpose unambiguous.

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

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

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' It also mentions the extra LLM call cost, helping the agent decide when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating safety. The description goes far beyond by detailing market resolution, classification, fan-out, response shapes, resolver contract, parent event extraction, news fallback, low-confidence handling, closed markets, wide spread detection, and resolution-rule risk. This comprehensive disclosure adds significant value 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 comprehensive but lengthy; however, it is well-structured with a clear front-loaded purpose statement followed by organized details (classifiers, fan-out examples, response shapes, safety notes). Every sentence provides valuable information, but some sections could be 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 complexity (3 parameters, no output schema, many sibling tools), the description covers all necessary aspects: input types, behavior, response structure, edge cases (low confidence, closed markets, wide spreads), and resolution rules. It is thorough and leaves no major gaps for an agent to misuse the tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description reiterates the same information (e.g., market input types, depth enum values) without adding new parameter-level meaning beyond what is already in the schema. Thus, it meets the baseline but adds no extra semantic 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?

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from siblings like polymarket_arbitrage and ask_pipeworx by focusing on a single bet's research, not general Q&A or arbitrage.

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

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

The description explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), providing clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, so it lacks exclusion guidance.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds context about data source (Comic Vine) and returned fields, going beyond annotations without contradicting them.

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

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

Single sentence efficiently conveys purpose, scope, and data content with 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?

With clear annotations, output schema, and one simple parameter, the description fully covers the tool's context and 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 0%, but the description implies the 'id' parameter via 'by ID'. No additional constraints or details are provided, but the single required number parameter is straightforward.

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 specifies verb 'detail' with resource 'character by ID', lists exact fields returned, and distinguishes from siblings by focusing on single comic-book characters.

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?

Clearly states usage by ID and for single character detail, providing context for when to use. Does not explicitly exclude other scenarios or mention alternatives, but 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 declare read-only and idempotent behavior; description adds that it returns summaries and supports pagination, providing useful context beyond what annotations offer.

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 (2-3 sentences), front-loaded with key purpose, and contains no superfluous 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 presence of an output schema and robust annotations, the description adequately covers what the tool returns and how to use it, though the 'sort' parameter is omitted.

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

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

Schema coverage is only 25%, but the description compensates by explaining the 'filter' parameter with an example and specifying valid filter types (name, publisher, date), though 'sort' remains undocumented.

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 browses Comic Vine's character directory, a specific resource, and lists filtering options, distinguishing it from singular 'character' or 'people' tools.

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

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

Provides clear usage context with filtering and pagination examples, but does not explicitly mention when not to use this tool compared to alternatives like 'character'.

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 readOnlyHint annotation, the description details what data is pulled for each type (company: 10-K financials with fiscal year handling; drug: FAERS counts, FDA approvals, trials), result sorting, and citation URIs. 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 trigger phrases and functional explanation. While it is a bit verbose, every sentence adds value—no filler. Minor improvement could be to group related details more tightly.

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

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

Despite no output schema, the description explains the return format (paired data + citation URIs) and result sorting. It covers both entity types, constraints (2–5 items), and edge cases (off-calendar fiscal years), making it complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning by explaining what each 'type' provides (company vs drug) and giving concrete examples for 'values' (tickers/CIKs for companies, drug names). This exceeds mere repetition.

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

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

The description starts with clear trigger phrases ('Compare X and Y', 'X vs Y') and states the tool performs side-by-side comparison of 2–5 companies or drugs. It distinguishes itself from sibling tools by advising to 'ALWAYS PREFER over sequential single-pack lookups', making the purpose unambiguous.

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

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

The description explicitly tells when to use this tool (comparing 2–5 entities) and provides strong guidance to prefer it over sequential lookups. Examples of user queries ('which is bigger', 'head to head') further clarify 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/openWorldHint/idempotentHint, and the description adds substantial context: account/auth needs, latency expectations, gap handling, contradiction flags, citation resolvability, and excerpting behavior. It explicitly states that findings are never invented when gaps exist.

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

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

The description is lengthy but information-dense and logically front-loaded with the account requirement. Every sentence contributes value, though some repetition (e.g., multiple mentions of ask_pipeworx) could be trimmed. Overall appropriately sized for a complex tool.

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

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

With no output schema, the description thoroughly explains return value structure (findings packet, verbatim evidence, confidence, source, gaps[], contradictions[], hop field, citation_uri), use cases, limitations, timing, and alternatives. It is self-sufficient for an agent to decide when and how to invoke it.

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

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

Schema covers both parameters 100%, but the description adds meaningful context beyond it: explains depth tiers in more detail (e.g., 'standard re-angles unanswered gaps', 'thorough chases leads'), notes paid plan for thorough, and clarifies that broad/multi-part questions are appropriate.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources...' with specific verbs and resource scope. It distinguishes itself from siblings by explicitly contrasting with ask_pipeworx and noting 'this 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?

Provides explicit guidance on when to use: 'Best for broad/multi-part questions over structured data' and when not: 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' Also mentions account requirements and fallback alternatives.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds useful context: returns top-N relevant tools with full input schemas and curated examples, 'ready to call directly, no second schema lookup needed.' This clarifies output format and usability 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 concise (about 4 sentences) and front-loaded: it starts with the core purpose, then lists use cases, what is returned, and when to call. Every sentence adds value 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?

Given no output schema, the description adequately explains what is returned (names, descriptions, full input schemas with curated examples) and that results are ready to call. It does not detail the exact output structure, but the high-level description is sufficient for a discovery 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 description coverage is 100%, but the description adds value by listing aliases (task, q, description, search) and providing concrete examples like 'look up FDA drug approvals'. It also mentions default limit (20) and max (50), which are not in the schema description. This enhances understanding of how to use parameters.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies the action (browse, search, look up, discover) and the resource (tools). It distinguishes from sibling search tools by noting this is for discovery and should be called first when many tools are available.

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 usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available.' It implies this is for exploration rather than getting a single answer, though it does not explicitly list 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?

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description details the tool's behavior: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and specifies the exact return fields (CIK, recent_filings with URIs, fundamentals with sorting, patents with sunset caveat, news, LEI). This goes well beyond annotations and provides full 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 detailed but front-loaded with example queries and the core purpose. While it is relatively long, each sentence serves a purpose (examples, usage guidance, return fields, caveats). It could be slightly more concise, but the structure is logical and efficient for the complexity of the tool.

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

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

Given that there is no output schema, the description does a good job explaining the return fields (CIK, recent_filings, fundamentals, patents, news, LEI). It covers key caveats (patents soft-fail, name resolution requirement). However, it lacks details on pagination, error handling, or rate limits, which would be helpful for complete 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?

The input schema has 100% coverage with descriptions for both parameters. The description adds value by providing concrete examples ('ticker "AAPL" or zero-padded CIK "0000320193"') and clarifying that names are not supported. This enhances the schema's semantics, but since the schema already covers the basics, the incremental value is moderate.

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 as 'full cross-source profile of a US public company in ONE parallel call', provides concrete examples of user queries, and explicitly distinguishes itself from chaining multiple single-source lookups. It also names the sibling tool 'resolve_entity' for name resolution, making the purpose unambiguous.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and instructs to use 'resolve_entity first if you only have a name'. It also states that names are not supported, providing clear when-to-use and when-not-to-use instructions.

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 destructiveHint=true and idempotentHint=true, so the description's 'Delete' adds minimal behavioral context. It does not contradict annotations.

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

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

Two sentences, no wasted words. The first sentence states the primary action, the second gives usage context. Front-loaded and efficient.

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

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

For a simple tool with one required parameter and no output schema, the description covers purpose, when to use, and relationships to siblings adequately.

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

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

Schema coverage is 100% and the parameter description 'Memory key to delete' matches the schema description. The tool description adds no further 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 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from siblings 'remember' and 'recall' by name.

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

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

Explicit use cases are provided: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with 'remember' and 'recall', aiding tool selection.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. It also clarifies output is a single text blob, which aids agent understanding.

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

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

Description is succinct with purpose front-loaded. Each sentence adds value (purpose, process, use cases). Minor redundancy ('production-ready', 'standard llms.txt markdown format') but overall efficient.

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

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

Given only 2 parameters, no output schema, and clear annotations, the description fully covers purpose, behavior, output format, and examples. No gaps remain for an agent to misuse the tool.

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

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

Schema coverage is 100% with both parameters described in the schema (url and max_links with defaults). Description does not add new parameter details beyond what schema provides, so baseline of 3 is appropriate.

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

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

Description states exactly what the tool does: generate a production-ready llms.txt file for any URL. It specifies verb 'generate', resource 'llms.txt file', and clearly separates it from sibling tools which are mostly search/entity tools.

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

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

Description lists three concrete use cases: client site indexing, own project drafting, competitor auditing. It lacks explicit when-not-to-use guidance, but given the tool's simplicity and lack of similar siblings, this is acceptable.

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. Description adds value by listing returned fields (cover date, store date, etc.), but no extra behavior (e.g., error conditions) is disclosed.

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?

One concise, front-loaded sentence with no wasted words, efficiently conveying purpose and key details.

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

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

Given low complexity (1 param, simple retrieval), rich annotations, and output schema, description covers necessary context. Could briefly mention source (Comic Vine) but not required.

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

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

Single required parameter 'id' is an obvious ID, but schema coverage is 0%. Description merely says 'by ID' without adding format or source hints; adequate for a trivial parameter.

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

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

Description states 'Comic Vine single comic-book issue detail by ID' followed by a list of included fields, clearly distinguishing from sibling tools like 'issues' (plural) or 'character'.

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

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

Implies use case (getting issue details by ID) but provides no explicit guidance on when to avoid this tool or compare with alternatives like 'issues', 'character', 'volume'.

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 and idempotent behavior. The description adds minor behavioral context by mentioning filtering options, but does not elaborate on pagination or response format beyond what annotations provide.

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

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

Two concise sentences with no redundancy. However, the first sentence is a noun phrase rather than an action-oriented verb phrase, which slightly reduces 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?

With an output schema present, return values are covered. However, parameter documentation is incomplete, and the description does not provide examples or clarify pagination behavior, making it partially lacking.

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' described). The description adds meaning for filter (volume, store-date, name) but ignores sort, limit, and offset, leaving significant gaps.

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

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

The description clearly states it's a list of single comic-book issues from Comic Vine, with filtering options. However, it does not explicitly distinguish itself from the sibling 'issue' tool, which likely fetches a single 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 gives context for usage ('For magazine-level comic data') but does not specify when not to use this tool or mention alternatives like 'issue' for specific issue details.

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

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

Annotations already mark readOnly, idempotent, openWorld. Description adds that it returns specific fields, only active by default with optional include_inactive. No contradictions.

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

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

Two concise sentences, no filler. Front-loaded with main action, then usage guidance. Efficient.

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

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

Simple tool with good annotations and full schema. Description adds enough context (field list, usage guidance) to be fully useful. No output schema but fields listed inline.

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 implicitly references the parameter by mentioning 'active subscriptions' vs 'include cancelled', but doesn't add new meaning beyond schema.

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

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

Description clearly states it 'list the caller's active subscriptions' and enumerates returned fields. Distinguishes from siblings 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?

Provides explicit when-to-use advice: 'review what you're monitoring before adding more or to find an id to cancel'. No direct exclusions but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the description's 'Browse' is consistent but adds no new behavioral insights beyond what is implied by 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 optional parameters, second gives exclusion and alternatives. No filler, front-loaded with essential info.

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 an output schema present, return values are covered. The description explains purpose, boundaries, and pagination; only missing guidance on 'sort' parameter. Overall sufficient for a simple directory lookup.

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 25% (only 'filter' described). The description adds that filter is by name and that limit/offset are for pagination, adding value beyond schema. However, 'sort' parameter remains unexplained, so not fully compensates.

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

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

The description specifies a unique verb-resource pair: 'Browse Comic Vine's comic-book creator directory', and explicitly lists creator roles. It distinguishes itself from sibling tools like 'character' or 'person' by clarifying the scope is comic creators only.

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 exclusion: 'NOT a general biography search', and names alternatives: 'for actors use TMDb, for general bios use Wikipedia'. This clearly guides when to use or avoid the tool.

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

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

Annotations already indicate safe read-only idempotent operation; the description adds context about the data source (Comic Vine) and specific returned fields, plus the restriction to comic-book creators, which goes beyond annotations.

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

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

The description is a single concise sentence that front-loads the purpose and key details, 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?

Given the tool's simplicity (1 parameter, output schema present, safety annotations), the description provides sufficient context about input and output, making it complete for the task.

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

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

The schema has 0% description coverage for the single 'id' parameter. The description does not explain the parameter beyond implying it identifies a creator, leaving the agent to infer meaning.

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

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

The description clearly states it retrieves a single Comic Vine creator detail with specific fields (name, country, birth/death, deck) and explicitly restricts to comic-book creators, distinguishing it from sibling tools like 'character'.

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 single creator lookup but provides no explicit guidance on when to use vs alternatives like 'character' or 'characters', nor when not to use.

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

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

All annotations are false, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow ('Filing without an account returns a claim_token'), free/cost status ('Free; doesn't count against your tool-call quota'), and the async review process ('The team reads digests daily'). These behavioral details go beyond the schema and annotations, giving the agent a clear picture of side effects and expectations.

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

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

The description is efficiently structured, front-loaded with the core purpose and then systematically covering scope, exclusions, token mechanics, rate limits, and cost. Every sentence earns its place; there is no redundant or filler content, keeping it appropriately sized for 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 has 4 params, a nested object, no output schema, and no annotation help, the description is remarkably complete. It covers return behavior (claim_token), usage boundaries, rate limits, cost, and content guidelines. It also addresses the 'Not sure?' identification question, making it self-sufficient for an agent to select and invoke correctly.

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

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

The schema covers 100% of the 4 parameters with detailed descriptions, providing a baseline of 3. The description adds meaningful beyond-schema meaning: message composition guidance ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), typical length ('1-2 sentences typical'), and clarifies the claim_token usage loop. These additions justify a score above baseline, though not 5 since the schema already handles most parameter semantics.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist,' with specific triggers (bug, feature/data_gap, praise). It also explicitly scopes to Pipeworx-served tools and excludes tools from other MCP servers, distinguishing it from alternative feedback channels.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data...', 'when a tool you wish existed isn't in the catalog', and 'when something worked surprisingly well.' It also gives a clear exclusion with an alternative: 'if the tool came from a different MCP server... file it with that server instead.' Additional context on how to identify Pipeworx tools ('Pipeworx tool names are the ones this connection lists') and how to phrase feedback further supports proper usage.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds significant value: data source (CF analytics-engine), no PII, cache duration (5min-1h), and output structure (pack, tool, count). 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 concise (four sentences), front-loaded with purpose, and uses bullet points for use cases. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description thoroughly covers purpose, usage, behavior, data source, caching, and privacy. No gaps.

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

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

Schema coverage is 100% with one parameter well-described. The description supplements by explaining the trade-off between windows ('hot right now' vs 'steady-state demand'), adding semantic meaning beyond the schema.

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

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

The description clearly states the tool returns trending tools, packs, and call volume over recent windows. It distinguishes itself from siblings like 'discover_tools' and 'search' by focusing on agent call popularity.

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

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

Three explicit use cases are provided (discovery, confirmation, alignment). No direct alternatives or when-not-to-use are mentioned, but the context is clear and helpful for an agent.

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

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

Annotations indicate readOnly, idempotent, non-destructive. Description adds extensive behavioral context: scanning logic, semantic anchor (Jaccard similarity), partition filter, fill check. 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?

Long but every sentence adds value. Front-loaded with main purpose, then elaborates modes. Could be slightly more concise but justified for tool complexity.

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

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

No output schema, but description compensates with response structure details (opportunities array, partition_check, fill_check). Mentions custom sizing tool. Covers all aspects needed for 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?

Schema coverage is 100% with descriptions. Description adds significant context: event/topic examples, behavior of each mode, fill check details. Adds value beyond schema.

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

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

Clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes three modes (trending scan, event, topic) with specific use cases, differentiating 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 tells when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Provides examples and warns when not to trade (realizable_edge_pp <= 0). Recommends 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?

The description amply covers behavioral traits beyond annotations: caching (1h at KV level), model details (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge computation (edge_pp_net, Kelly fractions), tradeable-edge knobs (min_liquidity, max_spread_pp), and diagnostics. It does not contradict the readOnlyHint, openWorldHint, idempotentHint, or destructiveHint annotations.

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

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

The description is lengthy but well-structured with clear segments, front-loaded purpose, and every sentence adds value. Some redundancy in explaining segments twice (in description and parameter categories), but overall efficient for the complexity.

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

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

Given 9 parameters and no output schema, the description is remarkably complete: it details the response structure (by_segment, fed_candidates, diagnostics), explains each model family, and describes return fields (edge_pp_net, kelly_fraction, etc.). No gaps 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?

Since schema coverage is 100%, baseline is 3. However, the description adds substantial meaning: e.g., slippage_pp explains zero trading fees but bid/ask depth, min_kelly explains why it skips small opportunities, min_partition_leg_kelly clarifies partition arbs. This extra context elevates the score above baseline.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection.

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 is built for 'what should I bet on today' and mentions that agents discover opportunities without paging hundreds of markets. It provides clear context on when to use the tool, but does not explicitly state when not to use it or list alternative tools for edge tracking. However, sibling tool names suggest alternatives.

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

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

The description provides extensive behavioral traits beyond annotations: snapshot TTL (60-day), gaps in data, decay computation from daily closes (not intraday), and detailed response fields. This adds significant value beyond the readOnlyHint and idempotentHint annotations.

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

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

The description is well-structured: summary, args, response with subsections, and limits. It is front-loaded with the core idea. While slightly verbose, every sentence adds value, making it efficient for an AI agent.

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

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

Given the tool's complexity, the description covers purpose, response format, edge cases (gaps, TTL), and limitations. No output schema exists, but the description details the return structure thoroughly.

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

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

The input schema covers both parameters with descriptions. The description paraphrases them and adds default values, but no additional semantics beyond the schema. Baseline 3 is appropriate due to high 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?

The description starts with a clear summary ('Edge persistence and decay telemetry') and uses specific verbs and resources. It does not simply restate the name but explains the core question it answers. While it doesn't explicitly differentiate from siblings, the purpose is highly specific and unambiguous.

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

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

The description implies usage for analyzing edge persistence and decay, but it does not explicitly state when to use this tool versus alternatives like polymarket_edges. No direct 'use when' or 'do not use when' guidance is provided.

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, and the description aligns fully. It adds rich behavioral context: what checks are performed, what return fields to expect (e.g., verdict, thin_legs, forced_directional_risk), and the risks involved. No contradiction with annotations.

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

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

Description is comprehensive but somewhat lengthy; however, it is well-structured with clear section headers (SINGLE-MARKET, BASKET) and front-loaded with the main purpose. Every sentence adds value, though a minor trim could improve conciseness.

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

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

Despite lacking an output schema, the description thoroughly enumerates return values for both modes (top_of_book, vwap_fill_price, slippage_pp, captures ratio, thin_legs, etc.) and explains edge cases (partial fills, straddle risk). It covers all necessary information for an agent to understand the tool's behavior and outputs.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds functional meaning beyond schema: explains how side defaults are determined per mode, how size_usd is interpreted (spend vs target proceeds vs settlement notional), and the mutual exclusivity of market vs event. This elevates usability beyond the schema alone.

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

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

Clearly states it performs a realizable-vs-theoretical edge check against live CLOB order-book depth. Distinctly separates single-market and basket modes and explicitly tells when to use it (before acting on polymarket_arbitrage or polymarket_edges trades above ~$500), differentiating it from sibling tools.

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

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

Explicitly states when to use this tool and when not to, including a concrete threshold (~$500) and reference to sibling tools. Explains the consequences of not using it (partial basket fills leading to unhedged directional positions). Provides mode selection criteria.

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

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

Beyond annotations declaring readOnly and idempotent, the description details the response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and warns that most pre-mapped topics return warnings. This adds significant behavioral context.

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

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

The description is verbose (over 300 words) and includes detailed explanations of modes, response, and safety fields. While well-organized, it could be more concise. The front-loading is good but the length reduces clarity.

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

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

Given no output schema, the description adequately explains the response (leg-by-leg prices, top spreads) and safety fields. It provides enough detail for an agent to understand the tool's behavior, though a more explicit response structure 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?

Schema coverage is 100%, so parameters are already documented. The description adds value by explaining the topic shortcuts, the override relationship between topic and explicit tickers, and provides examples. This goes beyond the schema.

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

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

The description clearly states the tool calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies the verb 'cross-venue spread' and differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and provides context about when compatibility warnings indicate non-tradeable spreads. It does not explicitly state when not to use, but the information is sufficient 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-mutating behavior. The description adds that it 'browses' and 'returns' data, consistent with annotations. It does not provide additional behavioral details such as rate limits, authentication requirements, or external API calls. Given the strong annotation coverage, this is adequate but adds minimal value beyond annotations.

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

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

The description is concise at two sentences. The first sentence immediately names the tool's purpose with concrete examples (Marvel, DC), and the second explains parameters and output value. Every word contributes meaning; no filler or redundancy. The structure is front-loaded and efficient.

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

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

For a simple list-browsing tool with robust annotations (read-only, idempotent) and an output schema, the description covers the essentials: what the tool does, how to filter and paginate, and what it returns. It explains the utility for downstream filtering, which is sufficient given the tool's low complexity. No significant 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 description coverage is only 25% (only the 'filter' parameter has a description). The description clarifies that 'filter' targets publisher names (and IDs per schema example), and that 'limit' and 'offset' control pagination. However, the 'sort' parameter is not mentioned, leaving its purpose unclear. The description partially compensates for low schema coverage but still leaves gaps, earning a mid-range score.

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: browsing the Comic Vine publisher list. It specifies the resource (publishers like Marvel, DC), actions (browse, filter by name, paginate), and output (IDs and names). The verb 'Browse' and the examples of well-known publishers immediately communicate scope, and the tool is distinct from sibling tools like 'character' or 'issues'.

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 when to use this tool: when you need publisher IDs/names to filter characters, volumes, or issues. It also mentions pagination and filtering, guiding usage. However, it does not explicitly state when not to use it or compare it to alternative tools like 'character' or 'issues', which could further clarify context. The guidance is clear but lacks 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scope (per user identifier), pairing with remember/forget, and the listing behavior when key is omitted. 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 three sentences, all essential, front-loaded with the core purpose, followed by usage context and pairing. No unnecessary words.

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

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

For a simple tool with one optional parameter and full annotations, the description covers purpose, usage, scope, and related tools. No output schema is needed, and the description is fully sufficient for an agent to use it 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 a clear description of the 'key' parameter. The description adds context about omitting the key to list all, which enhances understanding beyond the schema.

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

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

The description clearly states what the tool does: retrieve a value saved via remember, or list all saved keys when the argument is omitted. It names the verb 'retrieve' and resource 'memory key', and distinguishes it 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?

The description provides clear guidance on when to use the tool (look up previously stored context) and how to use it (omit key to list all). It mentions pairing with remember and forget, but does not explicitly contrast with unrelated siblings 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?

The description states mark_read:true flags events as read, a side effect, but annotations declare readOnlyHint=true, creating a contradiction. No other behavioral traits like rate limits or auth are disclosed.

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 the main purpose, and 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?

Since there is no output schema, the description adequately explains return fields (source, citation_uri, payload) and filtering parameters. However, it does not mention pagination or sorting order, which would be helpful.

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

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

Schema has 100% coverage with descriptions for all 5 parameters. The description adds value by explaining the purpose of mark_read and providing example filtering values like 'sec_8k' and ISO timestamps.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It details return fields and filtering options, distinguishing it from sibling tools like list_subscriptions.

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

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

The description explains when to use the tool (pulling alerts) and notes that polling works fine, but does not explicitly mention when not to use it or compare with alternatives like the direct API endpoint mentioned.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds details: fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), parallel call, soft-fail for USPTO, and return structure (changes[] grouped by source, total_changes, citation URIs). 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 comprehensive but slightly dense. Front-loaded with query examples, then systematically explains sources, parameters, and returns. No unnecessary repetition, but could be slightly more concise.

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

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

Despite no output schema, description explains the return structure (changes[] grouped by source, total_changes, citation URIs). Covers all three parameters with usage details, fallback logic, and source behavior. Sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100% (all params described). Description adds value: explains 'since' accepts ISO or relative shorthands with examples and typical usage, and clarifies 'value' accepts ticker or zero-padded CIK.

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

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

The description clearly states the tool's function as a 'change feed for a company in the last N days/weeks/months in ONE parallel call' and distinguishes it from sibling entity_profile by specifying when to use that instead.

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 example queries and explicit guidance: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' Also explains fallback behavior and parameter usage.

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

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

Despite annotations already indicating idempotentHint=true, destructiveHint=false, and readOnlyHint=false, the description adds important behavioral context: scoped by identifier, persistent vs anonymous session memory (24 hours), and that it's a write operation. 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, well-structured paragraph with front-loaded purpose. Every sentence adds value without redundancy. It is concise yet comprehensive.

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 write tool with two parameters and no output schema, the description covers all essential aspects: what it does, when to use, how it works (key-value, scoping, persistence), and related tools. No gaps.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds meaningful examples for keys and clarifies that value can be any text. 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 saves data for reuse across conversations or sessions, with specific verb 'save' and resource 'data'. It distinguishes itself from siblings like recall and forget by mentioning them as pairs.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides concrete examples (resolved ticker, target address, user preference, research subject). It also mentions pairing with recall and forget, giving clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds significant behavioral context beyond annotations: it explains graceful degradation for LEI/FIGI, explicit `unresolved` placeholders, source labelling for identifiers, and internal cascading through multiple endpoints. 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 example queries and clearly segmented by supported types. It is somewhat verbose but every sentence provides useful information, especially for the company type with its cross-source details. The internal labels (SUPPORTED TYPES, etc.) aid navigation, though it could be tightened 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?

There is no output schema, so the description carries the burden of explaining return values. It comprehensively details what the company type returns (CIK, ticker, LEI, FIGI, ownership, unresolved) and what the drug type returns (RxCUI, ingredient, brand, citation), including fallback behavior. This makes the tool self-sufficient for an agent to understand its 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% and the parameter descriptions are already detailed ('ticker (AAPL), CIK (0000320193), or name'). The main description does not add much for parameter meanings beyond restating accepted formats and mentioning type-specific return behavior, which is more about output than parameter semantics. Thus it meets the baseline but doesn't elevate it.

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 the specific verb 'resolve' with a clear resource (entity names to identifiers), supports it with multiple example queries, and distinguishes it from siblings by emphasizing ID lookup as the primary purpose. It explicitly states 'Use FIRST whenever you have a name but need an ID', making the purpose unmistakable.

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 explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also describes the supported entity types, what each returns, and notes that it replaces 2-3 manual lookups. While it doesn't name alternative tools, the 'Use FIRST' directive and clear ID-resolution context provide strong usage guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds value by revealing that it internally calls ai_visibility_check for each entity and returns a ranked list with score, confidence, signal density. 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 three sentences, front-loaded with the main action, and every sentence adds essential information without redundancy. Highly efficient.

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

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

Given the good annotations and 100% schema coverage, the description still provides needed behavioral context (internal call to ai_visibility_check, ranking, return fields). No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds context beyond schema by noting that the first entity in the array is treated as the 'subject' for narrative and rest as competitors, which aids correct usage.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description explicitly mentions usefulness for competitive AI-marketing audits and provides an example query. It implies when to use (multi-entity comparison) but does not explicitly state when not to use or name alternatives, though sibling ai_visibility_check is obvious.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds behavioral details: fans out to deps.dev and bundlephobia, partial failure handling, and a note about bundlephobia's first measurement taking 5-30s. 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 information-dense but efficiently structured: purpose first, then usage, then output details, then limitations and failure modes. 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?

No output schema, but description thoroughly lists return fields and behavior on partial failure. Covers all essential behavioral aspects for a composite API call.

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 full descriptions in schema (100% coverage). Description repeats scope acceptance but doesn't add significant new parameter-specific information beyond schema. Context on version default is implicit.

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

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

The description states 'Composite should I add this npm package to my project check in ONE call' and specifies the verb 'scan_dependency' and resource 'npm package'. It distinguishes it from sibling tools, which are unrelated.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also notes NPM ecosystem only; alternatives for other ecosystems 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, openWorldHint, idempotentHint, and destructiveHint. The description adds minimal behavioral context beyond 'search by name' and does not address pagination or rate limits. It does not contradict annotations.

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

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

The description is two concise sentences, front-loaded with the core purpose and followed by key restrictions. No redundant or vague phrasing.

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

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

Given the tool's complexity (4 parameters, output schema present) and sibling tools for specific resources, the description covers domain, usage, and exclusions adequately. It does not explain output format, but the output schema compensates.

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

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

Schema description coverage is low (25%), but the description adds meaning for 'query' (search by name) and 'resources' (lists possible types: character, concept, etc.). However, 'page' and 'limit' lack additional context.

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 it searches a comic-book reference database by name and lists resource types. It distinguishes from siblings by specifying the domain (comic books) and excluding ML research and real-world events, making the purpose unequivocal.

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 states when to use (comic-book entities) and when not to use (ML research, real-world events), with explicit alternative tools like arxiv_search_papers provided.

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. Description adds behavioral details: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K with truncation flag), return format (offsets, scores). Substantial 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?

Well-structured, front-loaded with core action. Four sentences, each adds value. Could be slightly more concise but clear and efficient.

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

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

Despite no output schema, description explains return format well (passages, offsets, scores) and covers limitations (200K cap, truncation). Pairs with sibling tool. Complete for its 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 descriptions. Description adds context about truncation for text parameter and provides examples for query. Slightly above baseline 3.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific use case (large text) and output (passages, offsets, scores). It distinguishes from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly tells when to use: when the record is too big for the prompt. Mentions pairing with ask_pipeworx_grounded, implying alternative. Clear context for usage.

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

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

The description adds substantial behavioral details beyond annotations: it requires authentication, returns an id, lists delivery constraints (SMS 10/day cap, phone verification, webhook auto-disable after failures), and explains the always-on feed. No contradictions with annotations.

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

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

The description is well-structured with a clear front-loaded purpose, followed by prerequisites, types, and delivery channels. While comprehensive, some sections (e.g., webhook signing details) could be slightly more concise without losing 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 tool's complexity (3 parameters, nested objects, 5 enum types, optional delivery with 3 channels and constraints), the description fully covers prerequisites, type-specific filters, delivery channels and their limitations, and retrieval methods. It provides all necessary context 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?

Despite 100% schema coverage, the description enriches each parameter with concrete examples and detailed explanations (e.g., sec_8k items, polymarket_edge topic, delivery options with constraints). It adds meaning beyond the schema's generic 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes the tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation and setup.

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, including prerequisites (requires Pipeworx OAuth account), and mentions alternative delivery retrieval via recent_alerts or a public URL. However, it stops short of explicitly stating when not to use this tool (e.g., for listing or unsubscribing), though these are implicitly covered by sibling names.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description specifies output format (category-bucketed example questions with exact tool+argument shapes) and usage modes (no args or 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 includes several example queries, which may be slightly verbose but are justified for an onboarding tool.

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

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

With one optional parameter and no output schema, the description fully covers what the tool returns and how to use it, including examples and the range of topics.

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

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

The schema already describes the optional topic parameter. The description adds context by explaining that omitting the parameter gives a cross-category spread, which goes beyond the schema description.

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

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

The description clearly states the tool is an onboarding entry point that returns categorized example questions with tool+argument shapes. It distinguishes from sibling tools by being the first tool to use for discovering capabilities.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning meta-tools. It lacks explicit when-not-to-use guidance but provides clear 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?

Adds value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain available. Consistent with annotations (idempotentHint, 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?

Two sentences that are front-loaded with the action. No wasted words; every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description fully covers purpose, usage constraints, and behavioral effects.

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?

Only one parameter 'id' with schema description 'Subscription id (uuid) returned by subscribe.' Description does not add additional meaning beyond schema. Baseline 3 for 100% 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 'Cancel a subscription by id', specifying the verb and resource. It distinguishes from siblings 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and the effect on data ('deactivated, not deleted'). Provides context but does not explicitly state when not to use.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses nuanced behavior: the full verdict enum, the critical distinction between could_not_verify (check did not happen, carries verification_error) and unsupported (no source exists), and the routing logic. This prevents misinterpretation of non-evidence results.

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?

Although lengthy, every sentence carries operational value: trigger phrases, dual-path logic, return contract, and caller-caveat. It is front-loaded with the most important info and structured logically, making the density justifiable.

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

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

With no output schema, the description fully explains the return contract (verdict enum, value with citation, reasoning) and the failure semantics. It also covers routing, alternatives, and use cases, making it self-sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and both parameters have clear descriptions. The description itself adds no new parameter-level detail beyond what the schema already provides, though it does reinforce the 'claim' concept with examples. This meets the baseline but does not exceed it.

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 concrete trigger phrases and states the verb+resource clearly: 'natural-language claim verification against authoritative sources.' It explicitly distinguishes this from sibling tools by noting it replaces 4–6 sequential calls and covers both financial and non-financial claims.

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

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

It gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates two pathways (SEC EDGAR/XBRL for company-financial vs grounded pipeline for anything else), effectively serving as an alternative to multi-step lookups.

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, etc., so the safety and idempotency are covered. The description adds no new behavioral context beyond the returned fields, but 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 a single, efficient sentence that front-loads the resource and lists output fields. No unnecessary words, though adding parameter info would improve structure without significant bloat.

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

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

For a simple tool with one required parameter and an output schema, the description covers the output well but neglects the input. This gap makes it slightly incomplete for an agent to correctly invoke the tool.

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

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

Schema description coverage is 0%, placing full burden on the description. However, the description does not explain the sole parameter 'id' or its purpose (e.g., 'Comic Vine volume ID'). The example provides minimal context, but the description fails to clarify what the id represents.

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

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

The description clearly states the tool retrieves Comic Vine single series/volume detail, listing specific fields (name, start year, publisher, issue count, deck description). It distinguishes itself from the sibling 'volumes' which likely handles multiple volumes.

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 a single volume but does not explicitly state when to use this tool versus the sibling 'volumes' or other similar tools. No alternatives or exclusions are mentioned.

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, covering safety and behavior. The description adds context (Comic Vine source) but does not disclose additional traits like rate limits or authentication.

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 superfluous content. The description is concise and front-loaded with the tool's core purpose.

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

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

For a simple list tool with output schema and comprehensive annotations, the description is adequate. However, it could provide more detail on parameter usage given the low schema coverage. The presence of output schema reduces the need to explain return values.

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 4 parameters with only 25% coverage (only 'filter' has a description). The description adds that filter can be by name or publisher, which partially compensates, but sort, limit, and offset remain undocumented in the 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 it is a list of comic-book series/volumes from Comic Vine, defines 'volume', and mentions filtering by name and publisher. This distinguishes it from siblings like 'volume' (singular) and other entity-specific tools.

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

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

The description implies usage for listing volumes with filtering, but does not explicitly state when to use this tool versus alternatives like 'volume', 'characters', or 'person'. No exclusions or when-not-to-use guidance is provided.

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