Mitre Cwe

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds crucial behavioral details: return structure (per-model {score, confidence, signals, raw_response} + combined view), default model (free Workers AI), and that Anthropic probing requires a user-provided API key with direct payment. 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 efficiently structured: first sentence states main function, second covers models, third gives return info and use cases. Every sentence adds unique value, with no redundancy or fluff. Front-loaded with 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?

For a tool with 4 parameters (1 required), no output schema, but detailed description covering return format and use cases, the definition is fully adequate. An agent can confidently invoke it without additional context. All critical information is present.

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

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

Schema description coverage is 100%, but the description adds significant meaning beyond schema: explains that 'entity' can be brand/product/topic, default model is Workers AI, models list includes 'workers-ai' (free) and 'anthropic' (paid), and context helps disambiguate. This aids correct parameter usage.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business/brand/product/topic and score visibility (0-100) per model.' It specifies the verb (probe, score), resource (LLMs, entity), and scope, differentiating it from siblings like scan_competitor_ai_presence which is competitor-focused.

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 outlines use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains default model vs. paid Anthropic option with API key. While it doesn't compare directly to sibling tools, the context is clear and sufficient for most agents.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description further adds that it routes to the right tool, fills arguments, returns structured answers with citation URIs, works on every tier, and is a single fast call. This goes beyond the 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?

The description is longer than average but highly information-dense. It is front-loaded with the key recommendation, provides concrete examples, and then explains alternatives. Each sentence earns its place, though minor trimming of the lengthy example list 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?

The tool is complex (routing to 5,529 tools) but the description covers what it does, when to use it, when to use alternatives, what results to expect (structured answer with citation URIs), and compatibility ('works on every tier'). No output schema exists, so the description adequately substitutes by describing the response format.

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

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

Schema coverage is 100% with the 'question' parameter and aliases clearly documented. The description itself does not add parameter-level details, but the schema already carries the semantic weight. The examples in the schema provide additional illustration, so a baseline of 3 is appropriate.

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

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

The description uses a clear verb ('ask') and resource ('pipeworx'), and goes far beyond that by explicitly stating it answers factual questions by routing to 5,529 tools across 1,455 sources. This clearly distinguishes it from siblings like deep_research and ask_pipeworx_grounded, and from web search.

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and explicitly names alternatives (ask_pipeworx_grounded, deep_research) with reasoning about when to step up. It also lists trigger phrases and examples, making usage boundaries 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds meaningful behavioral context beyond annotations: that candidate routing improvements are enabled live, no candidate is active now, and it is a full working router rather than a stub. This clarifies the experimental but functional nature without contradicting annotations.

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

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

The description is three sentences and front-loaded with the key fact (beta version). It explains current status, usage equivalence, and experimental purpose without unnecessary fluff. Slightly verbose due to the parenthetical about the retired candidate, but each sentence earns its place.

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

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

Given the simple schema, strong annotations, and no output schema, the description provides adequate context: it states the response shape matches ask_pipeworx, explains the experimental edge, and confirms it's fully functional. It doesn't elaborate on response structure, but the reference to the sibling tool fills that gap for agents already familiar with ask_pipeworx.

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

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

Schema description coverage is 100%, with the 'question' parameter and its aliases fully documented. The description only refers to 'same arguments' without adding new parameter-level detail, so it neither improves nor detracts from what the schema already provides.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same tools and arguments, and differentiates it from the stable sibling by its experimental routing improvements. It uses a specific verb ('ask') and resource context, making its 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?

Explicitly states when to use ('when you want the newest routing') and notes it currently matches ask_pipeworx exactly. It does not explicitly list when not to use it, but the beta/stable distinction is clear and the context is sufficient for an agent to choose appropriately.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description goes far beyond by detailing the return structure (answer, evidence, confidence, source, fetched_at), all possible refusal reasons, the constraint of using ONLY tool result content, and the extra LLM call cost. 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 information-dense but not bloated. It opens with a crisp purpose, explains routing and extraction, enumerates success/refusal return shapes, gives concrete use cases, and closes with a cost-based alternative. Every sentence contributes unique value.

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

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

For a complex tool involving routing, extraction, and refusal handling, the description covers the essential behavioral contract thoroughly. Although no output schema is provided, the description spells out the complete return format and refusal reasons. It also addresses cost trade-offs and domain applicability, making the tool predictable for high-stakes use.

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

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

Schema coverage is 100% with all parameters documented as aliases for the question. The description does not add further parameter-level detail; it focuses on behavior and routing. Baseline of 3 is appropriate because the schema fully covers the input 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads', specifying it extracts answers only from tool results and returns explicit refusals when data doesn't answer. It distinguishes itself from the sibling 'ask_pipeworx' by highlighting the grounded/evidence-based behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. Also gives exclusions and alternatives: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'. This provides clear decision boundaries.

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

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

The description goes far beyond the annotations (which already indicate read-only, idempotent, non-destructive). It details the resolution process, classifier fan-out, response shapes, resolver contract, parent event extraction, news fallback behavior, safety short-circuits, and resolution-rule risk. This provides comprehensive 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 comprehensive but very long and dense. While well-structured with section headers (RESPONSE SHAPES, RESOLVER CONTRACT, etc.), it could be more concise for an agent to quickly parse. Key points are front-loaded, but the sheer volume of detail reduces scanability.

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

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

Despite no output schema, the description thoroughly explains the response structure, error cases, and edge behaviors (e.g., low-confidence matches, closed markets, wide spreads). It covers all essential contextual information needed for correct invocation and interpretation.

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

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

With 100% schema coverage, the description adds meaningful context for each parameter. It explains that 'market' accepts slug, URL, or question text. For 'depth', it clarifies 'quick' vs 'thorough'. For 'include_raw', it describes the difference between summarized and full payloads with size estimates.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and verb (Research), distinguishing it from sibling tools like ask_pipeworx or deep_research which are more 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 lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it doesn't mention when not to use or compare directly to alternatives, the focus on Polymarket bets makes the applicability 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, destructiveHint, and idempotentHint. Description adds that it returns category description and member CWE IDs, providing useful behavioral context beyond annotations.

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

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

Description is a single sentence that efficiently conveys the tool's function and output. Some redundancy in listing example categories, but overall it is concise and front-loaded.

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

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

For a simple lookup tool with one parameter and comprehensive annotations, the description covers the tool's purpose, input style, and output. It does not detail error cases or non-existent IDs, but these are minor gaps given the tool's simplicity.

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

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

Schema has 0% description coverage, so description must compensate. It implies the 'id' parameter is a CWE category ID via examples (e.g., CWE-1004) but does not explicitly describe the parameter format or constraints, offering partial support.

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

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

Description clearly states the tool fetches a CWE category record, listing weaknesses in a family. Uses specific verbs like 'fetch' and 'returns', and distinguishes from siblings like 'weakness' which likely returns a single weakness.

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 provides example queries ('What CWEs fall under [category]') and explains the tool's purpose, but does not explicitly state when not to use it or name 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, destructiveHint, idempotentHint. Description adds value by explaining the hierarchical nature (immediate children vs. deeper hierarchy) and providing concrete examples, 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 extremely concise (2 sentences + example), front-loaded with the key action and resource, and every part adds value. No wasted words.

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

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

Given the tool's simplicity (1 param, output schema present, rich annotations), the description fully covers what the agent needs: purpose, parameter meaning, and behavioral context (hierarchy, immediate children). 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?

Although schema has 0% description coverage, the description fully explains the parameter 'id' through context ('CWEs derived from / under [N]') and an example ({'id': '79'}), making its purpose clear without needing additional schema text.

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 specific verbs ('list immediate children') and clearly identifies the resource (CWE in the relationship tree). It distinguishes from sibling tools like 'descendants' by specifying 'immediate children' and providing an example hierarchy.

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 (for immediate children) and hints at alternatives (e.g., 'descendants' for deeper traversal) via the hierarchical context, but lacks explicit when-not or alternative naming.

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 that indicate read-only, open-world, idempotent, non-destructive behavior, the description adds context about data freshness (10-K, FAERS), handling of off-calendar fiscal years, sorted results, and citation URIs. No contradiction with annotations.

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

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

The description is moderately long but front-loaded with common query patterns. While some repetition (e.g., listing multiple example phrases) exists, every sentence adds value. Could be slightly tighter but remains effective.

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

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

Despite no output schema, the description explains return format (paired data + citation URIs), sorting behavior, and covers both entity types thoroughly. For a comparison tool with moderate complexity, this is comprehensive.

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

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

Schema coverage is 100%, but the description adds meaningful extra context: for 'type' it specifies the data sources and metrics (revenue, net income, etc. vs adverse-event counts), and for 'values' it provides concrete examples (tickers/CIKs vs drug names). This exceeds basic schema descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 entities (companies or drugs) and distinguishes it from sequential single-pack lookups. Examples like 'Compare X and Y' and 'head to head' make the purpose immediately recognizable.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear guidance on when to use. It also details what each entity type (company/drug) retrieves and explains the data sources.

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, but the description adds substantial behavioral context: account/paid-plan requirements, 15-90s latency, depth hop mechanics with gap recovery, contradictions[] for standard/thorough, semantic excerpting, and the guarantee that citations are always resolvable. This goes far beyond the annotations.

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

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

The description is long but structured with a logical flow: account prerequisite → core value → when to use → alternatives → depth behavior → output guarantees. It front-loads the most critical info (account requirement, alternative tool). While dense, every sentence adds value and avoids redundancy, though it could be slightly more scannable.

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

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

No output schema exists, so the description carries the full burden of explaining return values. It fully covers the findings packet (verbatim evidence + confidence + source + fetched_at + citation), gaps[] handling, contradictions[], excerpting behavior, and latency. Combined with detailed parameter semantics and annotations, this is complete for a complex tool.

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

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

Schema has 100% parameter description coverage, so baseline is 3. The description adds meaningful nuance beyond the schema: depth:'thorough' requires a paid plan, standard is the default, and explains hop/contradiction behavior per depth. The question parameter is clarified as 'Broad/multi-part is fine'. This extra context justifies a 4.

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

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

The description clearly states the tool's specific purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in ONE call. It explicitly distinguishes from siblings: 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups and breaking news.

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 guidance: 'Best for broad/multi-part questions over structured data'. Clearly names alternatives: 'use ask_pipeworx instead' for unauthenticated users or single lookups, and 'prefer ask_pipeworx' for breaking/news topics. Also explains depth-level 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds the behavioral trait of returning transitive descendants, which is beyond what annotations provide. 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 fairly concise with two sentences and an example. It is front-loaded with the key concept. Could be slightly more streamlined, but overall effective.

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

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

Given the annotations and presence of an output schema, the description provides adequate context for exhaustive coverage analysis. It explains the concept and usage, though it could elaborate on the format of returned data.

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 one parameter 'id' with no description (0% coverage). The description does not explicitly define 'id' but implies it is a CWE identifier through examples. This is insufficient; it should directly state that 'id' is a CWE ID.

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 'full transitive descendants' of a CWE, using specific verbs like 'derived from' and examples. It distinguishes from sibling tools like 'children' by emphasizing exhaustive coverage.

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

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

The description explicitly states 'Use for exhaustive coverage analysis' and gives an example, implying when to use it. However, it does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already declare readOnlyHint and idempotentHint true. The description adds value by explaining the return format (top-N most relevant tools with names, descriptions, and full schemas) and that results are ready to call directly, which is beyond annotation info.

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

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

Two sentences with no wasted words. Purpose is front-loaded: 'Find tools by describing the data or task.' Every sentence adds value.

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

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

Given the tool's complexity (6 params, required), the description covers purpose, usage, and return format. It does not mention edge cases like no results, but the overall completeness is high for an agent to use effectively.

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

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

Schema coverage is 100% with descriptions. The description adds meaning by explaining that query accepts natural language with multiple aliases (task, q, description, search) and that limit max is 50 default 20, surpassing 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 it finds tools by describing the data or task, listing specific domains (e.g., SEC filings, FDA drugs). It distinguishes itself from sibling tools by being the discovery tool to call first.

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

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

Explicitly says to call this FIRST when you have many tools and want to see options. Provides context for when to use (browsing, searching) but does not explicitly state when not to use or give alternative tools for specific tasks.

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

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

The description discloses multiple behavioral traits beyond annotations: fans across multiple sources, returns specific fields, notes patents sunset May 2025 with soft-fail, and explains news fallback. No contradiction with annotations.

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

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

The description is lengthy but every sentence adds value given the tool's complexity. Front-loaded with example queries. Could be slightly more streamlined, but not wasteful.

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

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

Despite no output schema, the description thoroughly explains return values (up to 5 filings with URIs, sorted fundamentals, patents, news, LEI). Covers fallback behavior and future deprecation. Complete for a tool of this 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 already has 100% coverage with good descriptions. The description adds value by clarifying value format (zero-padded CIK) and reinforcing that type is only 'company'. Adds marginal but useful 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 clearly states the tool provides a 'full cross-source profile of a US public company' with explicit examples and distinguishes it from single-source chaining. It specifies the verb (profile/research) and resource (entity/company).

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

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

Explicitly advises to prefer this tool over chaining single-pack lookups for holistic views. It also provides a specific when-not-to-use case: if only a name is provided, use resolve_entity first. Clear context and alternative 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 indicate destructiveHint=true. Description adds context about clearing sensitive data and that it's a deletion action, but does not contradict annotations. Good addition without overstepping.

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 front-loaded action verb. No redundant words; every part 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?

Simple tool with one parameter and annotations present. Description covers purpose, usage, siblings, and behavioral implications fully 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 a clear description for 'key'. Description does not add extra parameter meaning beyond the schema, so baseline of 3 is appropriate.

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

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

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by name, earning top marks.

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 scenarios: context stale, task done, clearing sensitive data. Also mentions pairing with remember and recall for 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 the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the output format ('single text blob ready to drop at site-root/llms.txt') and the extraction process, enhancing transparency beyond the structured fields.

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 and front-loaded: it states the tool's function in the first sentence, then elaborates the process and use cases in two additional sentences. No redundant or unnecessary information.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what an AI agent needs: purpose, input meaning, output format, and typical use cases. Annotations provide safety context. No gaps identified.

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

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

Schema coverage is 100% with both 'url' and 'max_links' described. The description doesn't add parameter-level details beyond the schema, but it contextualizes their use (e.g., 'Full URL of the site to summarize' and 'maximum number of link entries'). Baseline 3 is appropriate as schema already provides adequate 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 uses a specific verb ('Generate') and resource ('llms.txt file'), and explains the process clearly. It distinguishes itself from sibling tools, none of which generate llms.txt, making its purpose unique 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?

Concrete use cases are provided (client indexing, personal project, competitor auditing), but no explicit when-not-to-use guidance is given. However, the context clear and the tool's specificity implies its appropriate 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 provide safety and idempotency info (readOnlyHint, destructiveHint, idempotentHint). Description adds value by specifying return fields (id, type, params, etc.) and default behavior (active subscriptions only). No contradictions.

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

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

Two sentences, no wasted words. First sentence states what it does and returns. Second sentence provides usage guidance. Concise and front-loaded.

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

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

Given no output schema, description compensates by listing returned fields. Covers purpose, usage, parameter effect, and return values. Complete for a simple list tool with one optional parameter.

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

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

Schema covers parameter with 100% coverage. Description adds context that default returns active subscriptions and 'include_inactive' extends that, giving semantic meaning beyond just listing the parameter name.

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?

States specific verb and resource: 'List the caller's active subscriptions'. Distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by mentioning purpose: 'review what you're monitoring before adding more or to find an id to cancel.'

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: 'to review what you're monitoring before adding more or to find an id to cancel.' Implicitly indicates not to use when intending to add or cancel subscriptions, guiding towards siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, indicating a safe, non-destructive operation. The description adds that it returns only immediate parents, which is useful behavioral context beyond annotations.

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

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

The description is concise: two sentences that are front-loaded with the purpose. Every word adds value, with no redundancy or unnecessary 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, the description does not need to explain return values. It covers the purpose and usage context adequately for a simple lookup tool. It does not discuss handling of invalid IDs, but the openWorldHint mitigates this.

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 a single parameter 'id' with 0% schema coverage. The description adds meaning by showing it is a CWE ID through example queries like 'What's the parent CWE of [N]'. However, it does not specify format or constraints, partially compensating for the lack of schema descriptions.

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

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

The description clearly states the verb 'list' and resource 'immediate parents of a CWE'. It provides example queries and distinguishes from sibling tools like 'children' and 'descendants' by specifying upward navigation.

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 to walk up to a more general weakness class', giving clear context for usage. It does not explicitly mention when not to use this tool or name alternative tools, but the sibling names and context imply 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 only set all hints to false, so the description carries the burden and fully delivers. It discloses that filing without an account returns a claim_token, how to later use that token to read status, the 5/day rate limit, that it's free and doesn't count against tool-call quota, and that the team reads digests daily. No contradiction with annotations.

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

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

The description is long but every sentence carries essential operational information: scope, exclusions, workflow, rate limits, and expected usage. It is front-loaded with purpose and usage, then flows into mechanics and constraints. Nothing is wasted, and the density is justified for a tool that needs to prevent misfiled feedback.

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

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

Despite having no output schema, the description fully covers what to expect (claim_token, later status read), the constraints (rate limit, quota), and the exact scope boundaries. It tells the agent how to identify whether a tool belongs to Pipeworx and what to do otherwise, making the tool self-contained for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaningful guidance beyond the schema: it explains the claim_token round-trip workflow, gives message length/format guidance (1-2 sentences, 2000 chars), and clarifies that context is optional structured context. This extra value warrants a 4.

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

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

The description opens with a specific verb phrase 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly identifying the resource and action. It also enumerates feedback categories (bug, feature/data_gap, praise), which distinguishes it from sibling tools like ask_pipeworx or discover_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 provides explicit when-to-use criteria ('when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... when something worked surprisingly well') and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection' with instruction to file elsewhere for other MCP servers. It also tells the agent what to include ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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 read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: data source (Cloudflare analytics engine), privacy (no PII), caching (5min-1h), and aggregate nature. No contradiction with annotations.

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

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

Two sentences plus three bullet points, all front-loaded with the core return value. Every sentence adds distinct value with no redundancy or filler.

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?

Without an output schema, the description adequately conveys what is returned (top tools, packs, volume) but lacks specifics on response structure (e.g., format of 'top'). For a trending tool, this is largely sufficient.

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

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

The single parameter (window) is fully described in the schema with enum and description. The tool description adds meaning by explaining how window length affects results ('hot right now' vs 'steady-state demand'), going beyond the schema.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a selectable window. It uses specific verbs ('returns') and identifies the resource (Pipeworx trending). Among 57 sibling tools, none share this purpose, making it well-distinguished.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical tools, aligning use cases). While no direct alternatives or exclusions are mentioned, the context is clear enough to guide appropriate invocation.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details: semantic anchor (Jaccard ≥0.30), partition filter (placeholder slugs, >20% placeholder returns null), fill check (realizable_edge_pp ≤ 0 means not tradable). 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?

Well-structured with clear sections for each mode, front-loaded purpose. Slightly verbose in places (e.g., repeating 'event (recommended for a specific market)') but information-dense and easy to follow.

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 fully explains return structure: opportunities[] with gap_pp, suggested_trade, reasoning, partition_check details, and fill_check behavior. Covers edge cases like placeholder filtering and Jaccard similarity. Complete for a complex tool.

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

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

Schema coverage is 100%, and description adds meaning beyond schema: explains event slug/URL acceptance and topic as seed question; details what each mode does and what to pass. Provides context for 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?

Description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. Mentions 'recommended' for event mode and explains the Jaccard filter. Lacks explicit 'do not use' conditions but provides clear guidance.

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

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

The description extensively discloses behavior beyond annotations: it details three model families, caching (1h at KV level), edge calculation (slippage, Kelly caps), and output structure. There is no contradiction with annotations (readOnlyHint, idempotentHint are consistent with a scanning tool).

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

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

The description is thorough but verbose (multiple paragraphs, technical details). While structured logically, a more concise version could improve readability without losing critical information.

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

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

Despite having no output schema, the description explains the full response structure (by_segment, diagnostics, per-opportunity fields) and even cache behavior. Given the tool's complexity (9 parameters, nested logic), this description is impressively complete.

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

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

Schema coverage is 100%, but the description adds significant value for each parameter, e.g., explaining slippage_pp as 'Polymarket has zero trading fees... bid/ask + thin depth typically eats 20-50bp,' and min_partition_leg_kelly's special behavior for partition arbs.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the target use case and contrasts with sibling tools like polymarket_arbitrage and polymarket_edge_tracker, which likely have different focuses.

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 discovery ('what should I bet on today') and explains how to use knobs to filter tradeable edges. It excludes Fed bets from ranking with a rationale, but does not explicitly state when not to use or provide direct alternatives. Sibling context partially fills this gap.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds critical behavioral details: snapshots are daily, decay computed from daily closes (not intraday), 60-day TTL for history, gaps mean no scan that day. 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 verbose with many details packed into a few sentences. While informative, it is not front-loaded and could be more concise. The response structure explanation is useful but adds length.

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

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

Given the complexity of the tool, the description fully explains the response structure (tracked, expired, snapshot_dates) and limitations (60-day TTL, decay computation). No output schema exists, so the description adequately covers what the tool returns.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description adds that days default is 14 and max is 30 (but omits the minimum clamp from schema), and repeats window defaults. This adds minimal value beyond the schema.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?' This specific purpose distinguishes it from sibling tools like polymarket_edges, which likely provides current edge data.

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

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

The description implies when to use (to assess edge freshness and decay) but does not explicitly state when not to use or mention alternatives. The guidance is clear but lacks explicit 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 indicate read-only, non-destructive behavior. The description adds valuable context: it walks the order-book ladder, returns specific fields like slippage and verdict, and highlights forced directional risk. 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 comprehensive but quite verbose, packed into one dense paragraph. While it uses bold labels to structure modes, it could be more concise and front-loaded for quick scanning.

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 details return values for both modes, including verdicts, capture_ratio, thin_legs, and forced_directional_risk. It covers all expected outputs and explains the rationale, making the tool self-contained.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds nuance, e.g., 'size_usd' in basket mode is settlement notional, and 'side' default logic. This enriches understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: checking realizable vs theoretical edge against live order-book depth. It distinguishes two modes (single-market and basket/partition) with specific verbs and resources, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs to use this tool before executing polymarket_arbitrage signals or trades above ~$500, and explains the risk of partial basket fills converting arbs into directional positions. While it doesn't list alternatives, the usage 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 indicate read-only, open-world, idempotent, non-destructive. Description adds extensive behavioral detail: two modes, compatibility_warning triggers, temporal alignment, skipped cross types, and when spreads are meaningless. 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 dense but well-organized: purpose, modes, response fields, safety fields. Every sentence adds value, though slightly verbose in safety field explanation. Could be more concise but still effective.

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

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

Covers all essential aspects for a data retrieval tool: purpose, modes, parameters, response structure, safety fields, and caveats. Lacks explicit output schema but response fields are described in text. Adequate given 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% and description adds meaning beyond property names: lists valid topic values, gives examples for tickers, explains override behavior. Provides context that helps agent choose parameters correctly.

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 computes cross-venue spread between Kalshi and Polymarket for same resolving question. Explains two modes (topic shortcuts and explicit tickers) and what output includes. Distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Provides explicit guidance on when to use topic mode vs explicit mode, and warns that pre-mapped topics often return compatibility_warning rather than tradeable spreads. Does not explicitly list when not to use, but the warnings effectively serve as 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 indicate readOnly, idempotent, non-destructive. Description adds value by clarifying scope and key omission behavior, with no contradictions.

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

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

Three concise sentences covering core action, usage context, and scope. No wasted words; information front-loaded.

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

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

For a simple tool with one optional parameter and no output schema, the description is comprehensive, covering retrieval, listing, scope, and pairing with related tools.

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

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

Schema coverage is 100% and includes parameter description. The description adds context that omitting the key lists all keys, enhancing understanding beyond the schema.

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

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

The description clearly states the tool retrieves values saved via 'remember' and can list all keys when 'key' is omitted. It distinguishes itself from sibling tools 'remember' and 'forget'.

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

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

Provides context on when to use (look up stored context, avoid re-deriving) and scope (identifier). Mentions pairing with 'remember' and 'forget', but could be more explicit about when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds useful behavioral details like the payload structure and the effect of mark_read:true. However, mark_read:true implies state mutation (marking events as read), which contradicts the readOnlyHint annotation. This reduces transparency and trustworthiness.

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

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

The description is concise with three sentences, each serving a distinct purpose: stating the core function, describing return payload and filtering, and explaining the mark_read usage and an alternative access method. No redundant information exists.

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 5 parameters (all optional), no output schema, and annotations covering safety, the description provides a good overview of purpose, return structure, filtering, and a usage example. It could mention limit and unread_only parameters briefly, but the schema covers them. Overall, fairly complete.

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

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

Schema coverage is 100%, so the schema already describes parameters. The description adds value by giving an example for type ('sec_8k'), specifying ISO timestamp format for since, and explaining the effect of mark_read. This goes beyond the schema alone, justifying a score above the baseline of 3.

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

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

The description clearly states the tool pulls fired events from a subscription feed and specifies what each event carries (source, citation_uri, payload). However, it does not explicitly distinguish this tool from siblings like list_subscriptions or subscribe, which could cause confusion about which tool to use for similar tasks.

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 context: filtering by type and since ISO timestamp, marking events as read to advance the feed, and that polling is fine. It also mentions an alternative access method (direct REST endpoint for scripts/dashboards), but lacks explicit when-not-to-use guidance or comparison with sibling tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, nondestructive. The description adds valuable behavioral details: parallel fetch, source fallback logic, supported 'since' formats (ISO date and relative shorthand with examples), and return structure (grouped changes, total count, citation URIs). No contradictions.

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

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

The description is longer than strictly necessary, but every sentence serves a purpose—examples, function, sources, fallback, alternative tool. It is front-loaded with queries and well-structured. Slight redundancy in the source enumeration could be trimmed, but overall it earns its length.

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

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

Given 3 required parameters and no output schema, the description covers all essential aspects: return format (grouped changes, total count, URIs), source behaviors and fallbacks, supported date formats, and clear differentiation from entity_profile. It is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, but the description enriches it further: it explains that 'since' accepts ISO dates or relative strings and suggests default values (e.g., '30d' or '1m'), and clarifies that 'value' can be a ticker or zero-padded CIK. This adds meaning beyond the schema.

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

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

The description begins with example queries, then clearly states the tool's function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from the sibling tool entity_profile, making 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 provides explicit guidance: 'Use entity_profile instead when you want the static profile ... regardless of window.' It also explains fallback behavior for news (GDELT preferred, GNews on rate limit/5xx) and notes USPTO's soft-failure condition. This clearly tells the agent when to use this tool and when not to.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds that the relationship is directional and lists possible values, which provides additional context but is not extensive.

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

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

The description is a single, well-structured sentence with a secondary clarifying note. Every part serves a purpose—purpose, result type, and usage guidance—without 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 two-parameter lookup tool with strong annotations and existing output schema, the description covers the core function and context. It could add more about the directionality or fallback behavior, but it is largely 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 0%, so description must compensate. It mentions 'two specific CWE IDs' and provides an example, but does not explicitly describe each parameter (source_id, target_id) or their formats/constraints. The example partially helps but is insufficient for full clarity.

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

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

The description explicitly states the tool fetches the directional relationship between two CWE IDs, listing the specific relationship types (parent/child/peer/precedes/can-precede). It identifies itself as a specialty tool, distinct from siblings like children, parents, and descendants.

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 clear guidance: 'most queries are better served by children / parents / descendants.' This indicates when to use alternatives. However, it does not specify exact conditions for using this tool over siblings beyond being a specialty case.

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

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

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds critical behavioral details: persistence depends on authentication, scoped by identifier, 24-hour retention for anonymous sessions. 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 modest in length, front-loaded with purpose, and all sentences add value. Could be slightly more concise but overall well-structured.

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

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

No output schema, but description explains storage model, scoping, retention, and usage pairing with recall/forget. Complete for a simple key-value tool with good 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?

Schema covers 100% of parameters with descriptions including examples. Tool description repeats some examples but adds no new meaning beyond the schema. Baseline 3 applies.

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

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

Description clearly states the tool saves data for reuse across sessions, with concrete examples (resolved ticker, target address). It also distinguishes from siblings 'recall' and 'forget'.

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

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

Describes when to use (when discovering something worth carrying forward) and pairs with recall/forget. Lacks explicit 'when not to use', but context is clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds significant behavioral context: identifiers are sourced and labelled, unresolved identifiers are explicitly returned under `unresolved` rather than omitted, LEI/FIGI enrichment degrades gracefully when upstream services are unavailable, and each call cascades through multiple lookup endpoints internally. This enriches the agent's understanding far 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 long and dense, but every segment adds information: example queries, supported types, output components, behavior under failure, and performance characteristics. It is front-loaded with usage examples. It could be better structured with line breaks, but no sentence is purely filler, earning 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?

For a complex lookup with no output schema, the description is remarkably complete. It specifies input formats for each type, output identifiers (CIK, LEI, FIGI, RxCUI), source provenance, unresolved handling, graceful degradation, and internal cascading. It also contextualizes the tool within the broader tool ecosystem ('official identifiers other tools require as input'). No critical behavior 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 description coverage is 100%, and the schema already documents both parameters with examples. The description restates this information (e.g., 'accepts ticker, CIK, or company name as input') and adds some nuance (e.g., 'when a ticker is implied' for FIGI), but the incremental value is modest. Baseline of 3 is appropriate since the schema carries 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 explicitly states the tool's core function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It gives concrete example queries ('What's the ticker for…') and distinguishes it from siblings by framing it as the 'FIRST' lookup step. This is a specific verb+resource pair with clear scope.

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

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

Usage guidance is explicit: 'Use FIRST whenever you have a name but need an ID.' It also implies when to use via input type examples and notes it replaces 2-3 manual lookups. However, it does not explicitly mention when NOT to use or name alternative tools, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density—useful context beyond what annotations provide.

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

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

Two sentences that are front-loaded with the core purpose, no extraneous words. Efficient and clear.

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 (multi-entity comparison, probing, ranking) and the lack of output schema, the description covers input, process, and output fields. It misses details like pagination or limits, but annotations indicate open-world and idempotent, so it is reasonably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds that the first entity is treated as the 'subject' for narrative purposes, which is extra semantic value beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes from the sibling ai_visibility_check by focusing on multiple entities and explicitly mentions competitive audits.

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

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

The description gives a use case ('competitive AI-marketing audits') and an example question, but does not explicitly state when not to use it or name alternative tools for single-entity queries. Guidance is implied rather than explicit.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description discloses partial failures, the 5-30s delay for bundlephobia's first measurement, and the sources_failed list in case of timeout. It accurately outlines the return structure.

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

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

The description is relatively long but well-structured, with the main purpose front-loaded. Each sentence adds value, though a slight reduction in length could improve conciseness.

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

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

Given the tool's complexity (multiple data sources, partial failures, ecosystem limitation), the description covers all necessary aspects: what it returns, how it behaves under failure, and its scope. No output schema exists, but the description adequately describes the return format.

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 that version defaults to latest published and that scoped packages are accepted, providing context beyond the schema.

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

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

The description clearly states the tool's purpose: a composite check for adding an npm package, covering license, advisories, bundle size, and more. It distinguishes itself by noting the NPM-only scope and referring other ecosystems to deps.dev:version directly.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides a clear exclusion for non-NPM ecosystems, guiding agents to alternative tools.

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

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

Reveals technical details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character cap (200K) with truncation flag. Annotations only convey readOnly, openWorld, idempotent, and non-destructive hints.

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

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

Concise three-sentence structure: first sentence defines the tool, second gives usage advice, third lists technical specs. No redundant information; every sentence serves a 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?

The description covers purpose, when to use, parameter roles, return format, and technical constraints (model, windowing, truncation). Despite no output schema, the return details are sufficient for agent selection.

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

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

Adds value over the schema by explaining the intended use of 'text' (e.g., SEC filing, article) and mentioning return format (passages with offsets and scores). Schema coverage is 100%, so baseline is 3; the extra context justifies a 4.

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

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

The description clearly states the tool does semantic search inside a fetched record, with specific outputs (passages, offsets, scores). It distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and noting when to use it.

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 guidance: 'Use when the record is too big to cram into the prompt.' Also advises pairing with ask_pipeworx_grounded for grounding, effectively directing the agent away from alternative tools.

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

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

Discloses behavioral traits beyond annotations: OAuth requirement, delivery channel constraints, webhook signing secret returned once, auto-disable after 10 consecutive failures. 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?

Single dense paragraph with clear structure: purpose, prerequisites, types with examples, delivery options with constraints. No wasted words; every sentence adds value.

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

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

Covers main aspects: what it does, prerequisites, types, parameters, delivery channels with constraints. No output schema but mentions returns subscription id and webhook secret. Missing error handling or cancellation but acceptable given complexity.

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

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

Schema coverage is 100%, but description adds significant meaning with type-specific parameter examples and delivery channel details (SMS verification, webhook signing). Baseline 3, raised to 4 for extra 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 clearly states the tool creates a proactive monitoring subscription to a live-data event stream. It specifies verb, resource, supported types, and distinguishes itself from sibling tools like list_subscriptions 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 specific usage context: requires Pipeworx OAuth account, lists supported types with example parameters, and delivery constraints (SMS verification, 10/day cap). Lacks explicit when-not guidance but still 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?

The description adds significant behavioral context beyond annotations: it states the output contains exact tool+argument shapes from a live catalog, and that it can be called with no arguments or a specific topic. 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 detailed but slightly lengthy; however, it is well-structured and front-loads the purpose. Every sentence provides useful information, earning a high score.

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 covers purpose, usage, output content, and guidance on when to use it. It is fully complete given the tool's complexity and available metadata.

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

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

The description adds meaning beyond the schema by explaining that omitting the topic gives a full spread, while passing a topic focuses the results. It also lists example topic values, which the schema's description does not.

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 category-bucketed example questions for onboarding, with explicit examples of user intents. It distinguishes itself from siblings like ask_pipeworx and entity_profile by being the entry point for learning what questions to ask.

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

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

Explicitly says to use this tool FIRST when you don't know what Pipeworx can do, and provides instructions for calling with or without the topic parameter. Lacks explicit when-not-to-use vs alternatives 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?

The description adds value beyond annotations by detailing ownership enforcement, deactivation vs deletion, and the link to 'recent_alerts' for historical data. No contradictions with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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 fluff. The first sentence states the core action, the second provides critical behavioral details. Efficient and well-structured.

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

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

For a simple tool with one required parameter and no output schema, the description covers the essential aspects: action, ownership constraint, effect (deactivation), and historical availability. It references a sibling tool ('recent_alerts') for additional context, making it complete.

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

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

The description does not add meaning beyond the input schema. Schema coverage is 100% and already describes the 'id' parameter as a uuid returned by 'subscribe'. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Cancel' and the resource 'subscription by id'. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and the deactivation behavior, which is unique to this tool.

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

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

The description provides a clear constraint ('ownership is enforced – you can only cancel your own subscriptions') and notes that the effect is deactivation, not deletion, with historical events still available via 'recent_alerts'. It does not explicitly mention alternatives or when not to use, but the context is clear.

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

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

The description goes well beyond the readOnlyHint and idempotentHint annotations by explaining the semantics of each verdict, especially the critical distinction between could_not_verify and unsupported. It also discloses behavioral traits like the two processing paths, citation inclusion, and reasoning output, with an explicit warning about misusing could_not_verify.

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

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

The description is long but well-structured, with each sentence delivering specific useful information (triggers, use case, financial vs. non-financial routing, verdicts, error handling, and the efficiency benefit). It's not redundant or padded, though it could be slightly tighter for optimal agent reading.

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 explains the return values, verdict meanings, error states (verification_error), and processing pipeline. It covers edge cases like unsupported claims and the distinction from could_not_verify, making it complete for a complex tool with no structured output documentation.

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

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

Schema coverage is 100% for both parameters (claim, tolerance_pct), so the baseline is 3. The description adds value by explaining that tolerance_pct overrides the implied tolerance, noting the default cap of 5, and giving concrete examples for the claim parameter, effectively enriching the schema-provided 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 function: natural-language claim verification against authoritative sources. It provides example trigger phrases and differentiates between financial claims (SEC EDGAR + XBRL) and all other factual claims, distinguishing it from sibling tools like deep_research or ask_pipeworx.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the automatic routing for different claim types. It doesn't name alternatives or explicitly state when not to use it, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds limited behavioral context. It notes the return includes metadata and CWE IDs but does not disclose any additional traits like rate limits or latency.

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

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

The description is two sentences with no extraneous words. It front-loads key aliases and examples, then explains the return value. Every sentence is informative.

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

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

Given the enriched annotations (readOnly, idempotent) and presence of an output schema, the description is complete. It tells the agent what the tool does, which IDs to use, and what data is returned.

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 'id' parameter. The description compensates by providing examples of valid IDs (1003, 1387, 1344) and explaining their mappings, adding 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 fetches curated CWE views, provides specific examples (e.g., view 1003, 1387, 1344) and distinguishes between types. The verb 'fetch' and resource 'curated CWE view' are specific, and the tool is differentiated from siblings like 'weakness' or 'category'.

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 what views are and lists specific view IDs with their meanings, which guides usage. However, it does not explicitly state when not to use this tool or describe alternative tools for searching or filtering weaknesses.

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=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds that the tool returns descriptions, examples, mitigations, related attacks, references, offering behavioral context beyond annotations. No contradictions.

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

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

Description is concise and front-loaded with sample queries, making purpose immediately clear. Every sentence adds value, though slightly longer than minimal. Could be tighter but remains 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 that an output schema exists (so return values need not be detailed), the description covers the tool's purpose, content returned, and usage contexts completely. No gaps for this complexity level.

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

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

Schema covers both parameters with descriptions. The tool's description adds example IDs and mentions optional view, but does not significantly enhance understanding beyond the schema. With 100% schema coverage, baseline is 3.

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

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

Description clearly states the tool fetches a single MITRE CWE record with details like description, examples, mitigations, related attacks, references. It provides example queries and lists use cases (security analysis, vulnerability triage, etc.). Distinct from siblings; no other CWE lookup tool exists.

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 explicitly suggests when to use this tool (security analysis, triage, training) and provides example IDs. However, it does not explicitly state when not to use it or compare with alternative sibling tools, though none are direct CWE lookups.

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