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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it routes to internal tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and takes one fast call. It stops short of disclosing possible failure modes or rate limits, but that is not a major gap given 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 front-loaded with the critical 'PREFER OVER WEB SEARCH' directive, followed by a structured breakdown of scope, usage, examples, and fallback tools. Some redundancy exists—the trigger phrases repeat the 'prefer over web search' idea—but every section serves a purpose for a broad meta-tool, and the hierarchy is 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?

For a tool with no output schema, the description compensates by explaining the return format (structured answer with pipeworx:// citation URIs). It covers the full decision space: what questions qualify, what domains are included, when to use siblings, and even how it handles breaking news. An agent has all the information needed to select and invoke this tool correctly.

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

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

Schema coverage is 100% with all six parameters being aliases for the question input. The description adds meaningful semantic guidance through concrete examples ('current US unemployment rate', 'Apple's latest 10-K') and by framing the parameter as a natural-language factual query. This goes beyond the schema's alias explanation.

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 and resource: routes questions to the right tool among 5,724 tools across 1,497 sources and returns structured answers. It clearly enumerates the covered domains (SEC filings, FDA drug data, FRED/BLS, etc.), and distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

It explicitly says to prefer this tool over web search and gives trigger phrases like 'what is', 'look up', 'find', and 'get the latest'. It also states when to step up to ask_pipeworx_grounded or deep_research, and clarifies that breaking-news questions are still handled here. This gives concrete, non-ambiguous usage direction.

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

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

The description goes well beyond annotations by disclosing the beta/experimental nature, the current lack of active candidates, the last retirement date, and the fact that it falls back to nothing and is a full working router. This gives the agent important behavioral expectations not available in the schema or 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 four sentences and each sentence contributes meaningful context: purpose, current state, usage, and fallback behavior. It is somewhat detailed due to the beta-specific nuances, but it remains focused and front-loaded with the core identity. No wasted words.

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

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

For a beta variant router with no output schema, the description covers what the tool is, what it currently does, how to use it, and what not to expect. It addresses the most likely agent confusion about fallback and equivalence to ask_pipeworx. The annotations handle safety/idempotency, so no critical gap remains.

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 schema already providing aliases and a description for the question parameter. The description only adds that the arguments match ask_pipeworx, which does not materially increase parameter understanding beyond the schema. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly identifies this as 'Beta version of ask_pipeworx' and explains that it is an 'identical universal router (same 5,724 tools, same arguments, same response shape)' with candidate routing improvements. This makes the tool's purpose specific and differentiates it from the stable ask_pipeworx sibling without ambiguity.

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

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

It explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not explicitly state when not to use it, but the note that 'currently matches ask_pipeworx exactly' provides practical guidance. This is clear context with a minor missing exclusion.

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

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

Discloses behavior far beyond the annotations: refusal mechanics with specific refusal_reason values, cost of one extra LLM call, and the success payload including verified evidence. Annotations already mark the tool as read-only and non-destructive; the description adds materially richer 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 dense but every clause earns its place: it defines the mode, distinguishes from ask_pipeworx, details return/refusal shapes, names use cases, and notes cost. Information is front-loaded with the core purpose before usage guidance.

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

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

Given the tool's complexity, the description covers routing, behavior, success and refusal outputs, cost implications, and when to prefer the cheaper alternative. No output schema exists, yet the description explains the return values sufficiently for an agent to invoke and interpret the tool correctly.

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

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

The schema already provides 100% coverage, documenting the question field and all aliases. The description does not need to add parameter semantics since the schema carries the burden, but it does add context about natural-language usage and routing behavior.

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 identifies a distinct verb and resource: a 'hallucination-resistant answer mode' that routes like ask_pipeworx but extracts answers only from tool results. It clearly distinguishes itself from the sibling ask_pipeworx by emphasizing evidence quoting and explicit refusals.

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 the tool: high-stakes reads where answers will be quoted, cited, or acted on, and where the agent must not invent facts. Also gives an explicit alternative: 'prefer ask_pipeworx for casual lookups', effectively covering the when-not condition.

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?

Even though annotations already mark this read-only, idempotent, and non-destructive, the description adds substantial behavior beyond that: never invents answers, returns explicit gaps[], contradictions[] for standard/thorough, stable pipeworx:// citations, semantic excerpting, latency expectations, and second-hop recovery behavior. No contradiction with annotations is present.

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

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

The description is long, but it is information-dense and every major block earns its place for a tool with this much behavioral nuance. It could still be tightened by trimming parenthetical statistics and some repetition of alternatives, so it is not a perfect 5.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It does so thoroughly: findings packet contents, citation format, fetchability guarantee, gaps[], contradictions[], hop field, latency, account requirements, and routing to alternatives. Nothing essential is missing.

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 baseline is 3. The description adds value beyond the schema by explaining what the depth levels do in practice (gap recovery for standard, chasing leads for thorough, contradictions scan) and clarifying that the question parameter expects natural-language broad/multi-part phrasing.

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 and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call.' It explicitly contrasts with open-web search and distinguishes itself from sibling ask_pipeworx by naming the alternative and the conditions for choosing 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: best for broad/multi-part questions, use ask_pipeworx for a single lookup, prefer ask_pipeworx for breaking/current-news topics, and use ask_pipeworx if not signed in. It also explains depth-level tradeoffs, leaving little ambiguity about selection.

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

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

Annotations already declare readOnlyHint, 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 already mark this tool read-only/idempotent, but the description adds materially: it discloses that returned pairs may carry both warning fields, that codes can indicate non-equivalence, that Kalshi fees are not modeled so spreads are gross, and that null temporal_alignment means unknown rather than aligned. 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 text is long but earned: every block covers a distinct operational concern (modes, response, warnings, skipped comparisons, fees). It is front-loaded with purpose and mode selection, though the volume of code-name enumeration makes it denser than strictly necessary.

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 carries the burden of explaining return semantics, and it does: leg prices, top_spreads_pp and flags, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment null meaning, and fees_note. It also tells the agent to read safety fields even on successful matches.

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 baseline is 3. The description adds real value by explaining that both invocation modes run the same matcher, that explicit parameters override the topic-mapped side, and by expanding the meaning of the pre-mapped choices. It does not need to repeat the schema's type/format details.

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

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

The description states the exact analytic result: a cross-venue spread between Kalshi and Polymarket for the same resolving question. It immediately separates this from the single-venue polymarket_* siblings and explains why the spread exists (participant pools differ 2-25pp).

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?

Two modes are explicitly spelled out with the exact pre-mapped topics versus explicit ticker/slug inputs. It also states the token-overlap matcher is identical in both modes and warns the agent not to treat pre-mapped topics as tradeable, including instructions to read compatibility fields even when matched_pairs > 0.

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?

Beyond the readOnly/idempotent annotations, the description discloses substantial runtime behavior: unmatched identifiers are listed under `unresolved` rather than silently omitted; ambiguous FIGI matches return `figi_candidates` and assert nothing; LEI/FIGI enrichment degrades gracefully if GLEIF or OpenFIGI is unavailable; each call cascades through multiple lookup endpoints; and ISINs resolve to the issuing legal entity. This gives an agent a reliable model of side effects and failure modes.

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

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

The description is front-loaded with user intents and the "Use FIRST" rule, then moves into supported entities. It is dense, and the large company-type parenthetical is a single long block, but the detail is task-relevant and compactly packed, with no filler; it earns a high but not perfect score for organization.

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

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

For a tool with two entity types, multiple identifier registries, no output schema, and several ambiguity/failure cases, the description covers all the essential call-time knowledge: accepted inputs, output identifiers per source, unresolved handling, candidate disambiguation, degradation behavior, and why the tool replaces several manual lookups. An agent has enough context to invoke it correctly in most scenarios.

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

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

The input schema already documents both parameters at 100% coverage, including the important entity-name-only rule for the `value` parameter. The description adds genuinely new semantic detail by stating that `value` also accepts ISINs and by explaining that an ISIN resolves to the issuing legal entity via GLEIF, which is not present in the schema. This supplements rather than merely repeats 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 opens with concrete user utterances ("What's the ticker for…" / "find the CIK for…") and then states the core action: resolve a user-spoken NAME to canonical/official identifiers. It further specifies supported types (company, drug) and the outputs (CIK, ticker, LEI, FIGI, RxCUI), and positions the tool as the prerequisite lookup step for other tools, distinguishing it from the sibling tools that consume IDs rather than produce them.

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 instruction "Use FIRST whenever you have a name but need an ID" is an explicit when-to-use rule, and the description goes on to differentiate inputs (name-only vs. noun phrase) and edge cases (ambiguous FIGI matches). It does not, however, name specific sibling tools to route to when an ID already exists or when another lookup is more appropriate, so it falls just short of a fully explicit when-not/alternatives statement.

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.