Hibp

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds value by disclosing the return format (per-model {score, confidence, signals, raw_response} + combined view) and cost implications ('you pay Anthropic directly for those calls'). 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 two sentences with no filler. It front-loads the primary action, then efficiently covers default behavior, optional key, return structure, and use cases. Every sentence earns its place.

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

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

Given the tool's complexity (4 params, no output schema, 1 required), the description covers the main behavior, return value, and use cases. It lacks details on error handling or rate limits, but with strong annotations and schema coverage, it remains sufficient.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning beyond the schema: it explains the default model, the role of `_apiKey` for Anthropic, and how `context` helps disambiguate. This enriches the semantic understanding.

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

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

The description explicitly states 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb and resource, and distinguishes itself from siblings like `scan_competitor_ai_presence` by focusing on LLM visibility scoring.

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

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

It provides clear contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains the default free model and the optional paid Anthropic probe. However, it does not explicitly exclude alternatives or state when not to use it.

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

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

Annotations already provide readOnly, idempotent, and non-destructive signals; the description adds substantial behavior beyond that: automatic routing, argument filling, and stable pipeworx:// citation URIs. No contradiction exists. It does not disclose edge cases like failure modes or rate limits, but for a safe read-only router this is solid 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 front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and then layers scope, behavior, examples, and a final directive. It is longer than the minimum but each section earns its place by helping the agent decide and call the tool.

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

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

With no output schema, the description compensates by explaining the return shape: 'structured answer with stable pipeworx:// citation URIs.' It covers scope, input style, examples, and priority over web search. The main gap is the lack of explicit differentiation between ask_pipeworx and its sibling variants.

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 the schema already documents the 'question' parameter and its aliases. The description contributes useful examples and phrasing cues but does not add meaningful parameter semantics beyond what the input schema already provides, landing at the baseline.

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

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

The description clearly identifies a routing/query tool: 'Routes the question to the right one of 5,621 tools' and returns 'structured answer with stable citation URIs.' It also names a broad concrete domain list. However, it does not distinguish ask_pipeworx from sibling variants like ask_pipeworx_beta or ask_pipeworx_grounded, leaving some differentiation to inference.

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

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

The description is explicit about preferring this tool over web search, saying 'PREFER OVER WEB SEARCH' and 'START HERE for most questions,' and it gives query-phrase patterns and examples. It does not provide when-not-to-use guidance for adjacent siblings such as ask_pipeworx_grounded, deep_research, or entity_profile, so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds beta-specific context: the tool is a full working router, currently matches ask_pipeworx exactly, and may have active candidates. This clarifies behavior beyond annotations without contradiction.

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

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

The description is four sentences, each carrying distinct information: beta nature, current equivalence, usage guidance, and no-fallback clarification. It is longer than strictly necessary but front-loads the key differentiator and avoids redundancy.

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

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

For a simple single-question tool with no output schema, the description provides enough detail: it references the full router behavior, aliases, and the fact it's identical to ask_pipeworx. The only minor gap is that it doesn't describe the response format, but since no output schema exists and the description says 'same response shape' as ask_pipeworx, it relies on that reference. This is acceptable given the lack of output schema.

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

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

Schema description coverage is 100% and every alias is documented as 'Alias for question.' The description only repeats that aliases are accepted, adding no new semantic meaning. Baseline score of 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 states a clear verb+resource ('Ask Pipeworx Beta') and immediately explains it is a universal router, distinguishing it from the stable sibling ask_pipeworx by the beta status and candidate routing improvements. It also references the exact same 5,621 tools and response shape, making the purpose unambiguous.

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

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

Explicitly tells the agent when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also mentions that results are compared against the stable router for merge decisions, providing clear context for 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses the refusal mechanism with specific reasons, the return format including evidence and confidence, and the constraint that answers come only from tool results. This adds substantial behavioral context that annotations alone do not provide, 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?

The description is compact yet information-dense, front-loading the core function and then layering routing, return format, usage criteria, and cost trade-off in a logical order. Every sentence adds new information with no filler, and it remains scannable despite 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?

The description is complete for an agent to correctly invoke the tool: it covers the purpose, behavior, success/refusal return structures, usage criteria, and the distinction from the sibling. Given no output schema exists, the description explicitly supplies the return shape, and the parameter guidance is sufficient. 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?

The schema covers 100% of parameters (all aliases for 'question'), so the baseline is 3. The description adds value by specifying what kinds of questions are appropriate (high-stakes factual claims) and implies the question should be answerable from source data. This is a modest increment beyond the schema, justifying 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 identifies the tool as a hallucination-resistant answer mode that extracts answers from tool results, explicitly distinguishing it from the sibling ask_pipeworx by highlighting the grounded extraction step. It states the verb 'ask' and the resource 'Pipeworx' with a specific qualifier, leaving no ambiguity about what it does.

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

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

The description provides explicit guidance on when to use (high-stakes reads where answers will be quoted, cited, or acted on) and when not to use (casual lookups, preferring ask_pipeworx). It also mentions the extra LLM call cost as a trade-off, which is concrete and actionable for an agent.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: market resolution, classifiers, fan-out examples, response shapes, resolver contract, parent event extraction, news fields, safety short-circuits, spread warnings, and resolution-rule risk. No contradiction with annotations.

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

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

Description is very long and dense with multiple paragraphs. While it front-loads the main purpose, it contains many details that could be streamlined. Acceptable for a complex tool but not concise.

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

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

Given the tool's complexity (many classifiers, fan-out patterns, response shapes), the description covers all essential aspects: input types, resolution process, evidence sources, response fields, safety mechanisms, and edge cases. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100% with descriptions for market, depth, include_raw. The description adds significant context: market can be slug, URL, or question text; depth enums explained; include_raw explains size trade-off (keeps responses under ~20KB vs 50KB-500KB). Adds 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?

Description clearly states the tool researches a Polymarket bet by fetching relevant Pipeworx data. It specifies input types (slug, URL, question text) and provides use cases. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on research rather than arbitrage or edge tracking.

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

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

Explicitly mentions when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides examples of fan-out per bet type. However, it does not explicitly state when not to use or compare directly to siblings, relying on context from the tool name and sibling list.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the requirement of an API key and the return format (breach names), but does not disclose potential rate limits or other behavioral traits. With annotations covering safety, a score of 3 is appropriate.

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

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

The description is two sentences, front-loading the purpose and critical requirements. Every sentence adds value without redundancy.

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

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

Given the presence of annotations and output schema (not shown but noted), the description provides adequate context about return value and usage. It could mention pagination or error cases, but overall it's sufficient.

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

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

The input schema has 100% coverage with descriptions for both parameters. The description reiterates the API key requirement and mentions truncate behavior implicitly, but does not add significant new semantic meaning beyond the schema.

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

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

The description clearly states 'Look up breaches an email account has been seen in', which is a specific verb+resource. There are sibling tools like check_password and get_breach, and this definition effectively distinguishes itself by focusing on breaches for an email account.

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: 'REQUIRES a paid HIBP subscription key (pass _apiKey)' and recommends combining with get_breach for details. It does not explicitly state when not to use, but the context is clear enough for an agent to decide.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but description adds critical context: password is SHA-1ed locally, only first 5 hex chars sent, password never transmitted. This fully discloses behavioral traits beyond annotations.

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

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

Three concise sentences: first states purpose, second explains k-anonymity mechanism, third clarifies no transmission. Every sentence is necessary and efficient.

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

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

Given a single parameter, presence of output schema, and clear annotations, the description sufficiently covers purpose, security mechanism, and result format. 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?

Input schema has 100% coverage with description 'Password to check (stays inside the worker)'. The tool description reinforces that the password remains local, adding semantic meaning beyond the schema's basic description.

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

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

Description clearly states the tool checks password against breach databases with specific verb 'check'. It implicitly distinguishes from 'check_password_prefix' sibling by describing full k-anonymity mechanism, but does not explicitly differentiate.

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

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

Provides clear context for when the tool is appropriate (breach checking) and implies privacy-preserving usage via k-anonymity. Does not explicitly mention when not to use or alternatives, but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by explaining the k-anonymity mechanism and that the tool returns multiple suffixes and counts, which is beyond what annotations provide. 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?

Two sentences with no wasted words. All information is front-loaded. Every sentence adds value.

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

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

For a simple tool with one parameter, a clear description, and an output schema, the description fully covers the tool's behavior and use case. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by stating the parameter is a 'prefix of a SHA-1 password hash', which is richer than the schema's '5 hexadecimal characters'. This helps the agent understand the 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 performs a k-anonymity lookup using the first 5 hex chars of a SHA-1 password hash and returns SHA-1 suffixes with pwned counts. It uses specific verbs and resources, and the purpose is unambiguous.

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

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

The description explicitly advises using this tool 'if you're hashing client-side and only want to send the prefix', providing clear context for 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 safety (readOnlyHint, idempotentHint) and behavior (openWorldHint). The description adds value by explaining it is a single parallel call, handles fiscal years correctly, sorts by primary metric, and returns 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 compact (3-4 sentences) with front-loaded trigger examples. Every sentence adds value—no redundancy or fluff. Structure is well-organized: triggers first, then behavior, then data specifics.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, data sources, metrics, sorting, and return format (paired data + URIs). It is nearly complete, though it could mention that output is unschema'd JSON or list. Still sufficient for agent use.

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

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

Schema coverage is 100%, so parameters are documented. The description adds significant meaning: for 'type', it details data sources per entity (SEC EDGAR for companies, FAERS/FDA for drugs); for 'values', it provides examples and constraints. This goes beyond the schema and helps correct tool invocation.

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 ('compare', 'pulls', 'returns') and explicitly states it handles 2–5 companies or drugs in a parallel call. It distinguishes from siblings like entity_profile by noting it replaces 8–15 sequential lookups, making the tool's purpose clear and unique.

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 trigger phrases ('Compare X and Y', 'which is bigger', 'rank these companies') and states preference over sequential lookups. However, it does not include exclusion criteria (e.g., when more than 5 entities or non-financial/drug comparisons), which would improve clarity.

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, openWorld, idempotent, non-destructive), the description discloses concrete behaviors: parallel routing to 5,621 tools, decomposition into facets, return packet structure (evidence, confidence, source, timestamp, citation), gap handling (never invents), contradictions, excerpting of large records, and expected latency (15-90s). It also notes paid-tier and account requirements.

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 contributes unique info: prerequisites, alternatives, behavior, return details, depth semantics, timing. It is front-loaded with the critical account requirement. However, it is a single dense paragraph without structural breaks, which could impede scanning. Density is justified for the complexity, so 4.

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

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

Given complexity and no output schema, the description is remarkably complete. It specifies the findings packet contents, gap representation, citation resolvability, depth effects, and runtime. An agent has all needed info to invoke correctly and interpret results.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds value by clarifying depth tiers' behavioral implications (gap recovery, contradictions, iteration) and latency, plus the paid plan requirement for 'thorough'. This goes beyond schema but schema already carries much weight, so not a 5.

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 tool performs multi-source grounded research across Pipeworx's structured data sources in one call, explicitly distinguishing it from open-web search and the single-lookup sibling ask_pipeworx. It specifies the resource (structured data) and the action (research), and names its appropriate use case.

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

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

The description gives explicit conditions: use ask_pipeworx when not signed in, for single lookups, or for breaking/current-news topics; use deep_research for broad/multi-part questions over structured data. It names alternatives and the criteria, leaving no ambiguity.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds relevant behavioral context: returns top-N relevant tools with 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' 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 a single paragraph that front-loads the core purpose and usage. While it enumerates many domains, each sentence contributes to clarity. It could be slightly more concise 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?

For a discovery tool with 6 parameters and no output schema, the description fully explains what the tool does, when to use it, and what it returns (top-N tools with schemas and examples). It covers all essential context an agent needs to 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 description coverage is 100%, so the schema already documents all parameters. The description mentions that the 'query' parameter accepts natural language and lists example queries, but this adds minimal value beyond the schema's property descriptions and examples.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and explains the return value (top-N tools with schemas), effectively distinguishing it from sibling tools that perform specific 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 explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage guidance, though it lacks explicit 'when not to use' instructions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds significant behavioral context: fans out across multiple sources, returns specific fields, details patent sunset and soft-failure, and explains news fallback. 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 a single paragraph but is information-dense. It is front-loaded with query examples and includes explicit instructions. However, it could be slightly more structured (e.g., bullet points for the return fields) to improve scannability. Still, every sentence earns its place.

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

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

Despite no output schema, the description comprehensively details the return structure (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). It covers input types, fallback behaviors, and failure modes. The description is complete for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100%. Parameter descriptions are clear: type is enum with only 'company', value is ticker or zero-padded CIK. The description adds value by explaining the value format, explicitly stating names are not supported, and directing to resolve_entity for names.

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 natural language examples and clearly states it provides a full cross-source profile of a US public company. It distinguishes itself from chaining individual lookups by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and lists the specific data sources and fields returned (cik, recent_filings, fundamentals, patents, news, LEI).

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 when to use: when the user asks for a holistic view. Provides clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' Also mentions potential failure modes (patent API sunset) and fallback behavior (news via GDELT→GNews fallback).

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description confirms destructive action but adds no further behavioral details beyond annotations.

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

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

Two sentences: first states action, second gives usage scenarios. Front-loaded and efficient with no wasted words.

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

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

Simple one-param tool with destructive annotations. Covers purpose and usage well, but lacks mention of return value or error behavior. Minor gap given 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 coverage is 100% and describes 'key' sufficiently. Description only says 'by key', adding no extra 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?

Description clearly states 'Delete a previously stored memory by key', specifying verb and resource. Distinct from siblings like 'remember' (store) and 'recall' (retrieve).

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

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

Provides explicit when-to-use scenarios: stale context, task done, clear sensitive data. Mentions pairing with remember/recall. Lacks explicit when-not, but context is clear enough.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds internal steps (fetches page, extracts title/description/links, emits standard format) and output expectation. 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?

Three sentences: purpose, process, use cases. No fluff, all information earns its place. Front-loaded with the key action.

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

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

Tool has only 2 params and no output schema. Description covers what, why, how, and output format. For its simplicity, it is fully complete.

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

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

Schema coverage is 100% with clear descriptions. The description does not add new parameter details but mentions 'title/description/key links' which indirectly relates to max_links. 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?

Clearly states verb 'generate' and resource 'llms.txt file'. Distinguishes from sibling tools (which are mostly search, password, breach, and market tools). The specific output format and target users are explicit.

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

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

Explicitly lists three use cases: indexing client sites, drafting for own projects, auditing competitors. While no alternatives or exclusions are given, the use cases are clear and distinct from siblings. No sibling tool overlaps.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds case-sensitive constraint but doesn't detail return behavior beyond 'full breach metadata'. No contradictions.

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

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

Single sentence, front-loaded with verb and resource, no filler. Every word earns its place.

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

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

With one parameter and an output schema, the description explains exactly what input is needed (breach name from list_breaches) and what is returned (full metadata). Complete for a simple fetch 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 covers 100% of parameters and describes 'name' as case-sensitive. Description reinforces with examples (e.g., 'Adobe', 'LinkedIn'), adding value by linking to list_breaches output.

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

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

Clearly states 'Fetch a single breach by name', identifies the resource (single breach), and distinguishes from sibling tool list_breaches by referencing the 'Name' field from that 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?

Provides clear context: use this when you have a specific breach name from list_breaches. Doesn't explicitly mention when not to use, but the instruction is sufficient for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds that it's an HIBP catalog and lists return fields, but no additional behavioral traits like rate limits or pagination.

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, efficient and front-loaded. Could be slightly more structured (e.g., bullet points for return fields), but overall concise and 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 low complexity (single optional parameter) and existence of output schema, description fully covers what the tool does, including return fields. 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?

Input schema has 1 parameter with description 'Restrict to a specific breached domain'. Description also mentions domain filter. Schema coverage is 100%, so description adds minimal extra meaning beyond schema.

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

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

Description clearly states it lists all publicly-known data breaches from HIBP, with optional domain filtering. It distinguishes from siblings like get_breach (single breach) and check_account.

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?

States optional domain filter but does not explicitly specify when to use this tool vs alternatives like get_breach or list_data_classes. Usage context is implied but lacks direct guidance.

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

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

Annotations already provide comprehensive behavioral hints (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). The description adds 'Canonical list', which might imply completeness, slightly conflicting with openWorldHint (suggesting non-exhaustive). Apart from that, the description does not add significant 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 two sentences long and immediately front-loads the essential information. Every word serves a purpose; no filler or redundancy.

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

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

Given the tool has no parameters, comprehensive annotations, and an output schema, the description adds enough context about the purpose and use case. It lacks explanation of the output format, but the output schema can cover that. A minor gap is the possible contradiction with openWorldHint, but overall 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?

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description adds value by explaining what data classes are with examples, which aids 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's function: 'Canonical list of HIBP data class tags'. It uses a specific verb ('list') and resource ('data classes'), and provides examples like 'Email addresses', 'Passwords'. Among siblings, no other tool appears to list data classes exclusively, so it distinguishes well.

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 mentions 'Useful for filtering breaches', which gives a usage context. However, it does not explicitly contrast with siblings like 'get_breach' or 'list_breaches', nor does it state when not to use it. The guidance is present but minimal.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description focuses on additional context like return fields (id, type, params, etc.) and that it lists only active subscriptions by default. This adds value beyond the annotations without contradiction.

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

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

Two sentences, front-loaded with purpose, each sentence adds value. No redundant or extra content.

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

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

Given the simple list tool with one optional parameter and annotations covering safety, the description fully explains what it does, what it returns, and when to use it. No output schema is needed as return fields are listed.

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

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

Schema coverage is 100% for the single parameter 'include_inactive,' which is already described in the schema. The description does not add any parameter-specific information, so it meets 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?

Description explicitly states 'List the caller's active subscriptions,' clearly identifying the verb (list) and resource (subscriptions). It distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on reading rather than creating or deleting.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to choose this tool over alternatives, making it highly 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 are all false, giving no safety or behavioral signal, so the description carries the full burden. It discloses rate-limiting ('Rate-limited to 5 per identifier per day'), cost semantics ('Free; doesn't count against your tool-call quota'), the claim_token feedback loop ('Filing without an account returns a claim_token; pass it back later...'), and the team's digest pace ('The team reads digests daily'). This is rich, non-obvious behavioral context beyond the schema.

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?

Though the description is long, every sentence earns its place: purpose, usage triggers, exclusion, formatting guidance, token mechanics, team cadence, rate limits, and pricing. It is front-loaded with the core action and then logically expands. No filler or redundant restating of the title or schema 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?

This tool has no output schema, so the description must cover the return value and follow-up behavior. It explains the claim_token return and how to use it for later status checks. It also addresses edge cases (different MCP server, unsure which tool) and policy constraints (rate limit, quota). For a feedback tool with four parameters and no output schema, this is complete and self-sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token parameter's lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed and what changed'), which the schema only identifies as reading a reply. It also adds practical guidance for the message parameter ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). It doesn't elaborate on the context object, but the schema already covers that adequately.

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

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

The description opens with a clear specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly enumerates the feedback types (bug, feature/data_gap, praise) and is clearly distinct from all sibling tools, which focus on data retrieval, research, or account management. There is no ambiguity about what this tool does.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a strong exclusion rule—if the tool came from a different MCP server, file with that server instead—and instructs not to paste the end-user's prompt. This completely covers usage vs 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds: caching behavior (5min-1h), data source (CF analytics-engine), and privacy guarantee (no PII). 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 concise with three sentences covering output, use cases, and behavioral notes. Each sentence provides distinct value without redundancy or fluff.

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

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

Despite no output schema, the description explains the output structure (tools, packs, volume) and caching details. With only one optional parameter, the description is fully adequate for correct agent usage.

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

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

Schema coverage is 100% with a well-described enum. The description adds default window (24h) and explains the semantic difference between short and long windows, providing additional context for parameter selection.

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

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

The description specifies that the tool returns top tools, top packs, and total call volume over a window (24h, 7d, 30d). It clearly distinguishes from siblings by focusing on trending/aggregate signal rather than direct queries or actions.

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, and checking use-case alignment. While it doesn't state when not to use, the context is clear and helpful for 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 indicate readOnly, openWorld, idempotent, and non-destructive. Description adds extensive behavior: monotonicity and partition checks, semantic anchor threshold (0.30 Jaccard), partition filter for placeholder slugs, fill check against live CLOB depth, and condition for not trading. 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?

Long but well-structured with clear sections (overview, modes, filters, response, fill check). Front-loaded with main purpose. Every sentence adds value, though could be slightly more concise.

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

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

Given the tool's complexity, the description is highly complete. Covers all modes, algorithm details, response fields, edge cases (placeholder filtering, low similarity), and references polymarket_fill_risk for custom sizing. No output schema, but response structure is well described.

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

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

Schema coverage is 100% with two parameters (event, topic). Description adds significant value by explaining modes, providing example values, and noting that full Polymarket URLs are accepted. Goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and provides specific examples. It stands apart from siblings 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?

Explicit instructions for when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. Also advises against trading when realizable_edge_pp <= 0. Provides clear context for 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=true and idempotentHint=true, and the description adds substantial behavioral context: it explains the three response segments, caching behavior (1h KV-level), and that Fed bets are unreliable without paid OIS/SOFR data. No contradictions.

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

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

The description is front-loaded with purpose and then structured around model families and response format. However, it is quite long and could be trimmed while retaining key information. It earns a 4 for being well-organized despite verbosity.

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 (9 parameters, no output schema), the description is exhaustive: it details the response structure (by_segment, fed_candidates, _diagnostics), explains each knob thoroughly, and includes caching details. An agent can fully understand the tool's behavior.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add new meaning beyond what the schema already provides for each parameter. For example, limit, window, min_kelly, etc., are equally described in both.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, and it's built for the 'what should I bet on today' use case. This clearly distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 extensive context on when to use the tool, including segments and tradeable-edge knobs. It also notes that Fed bets require paid data. However, it does not explicitly state when not to use it or mention alternative tools, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: it returns tracked, expired, and snapshot_dates arrays; notes data gaps from cache-misses; explains that decay numbers come from daily closes, not intraday; and mentions the 60-day TTL limit. No contradictions with annotations.

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

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

The description is well-structured with sections for purpose, args, response, and limits. It front-loads the key question. While slightly verbose, every sentence adds value. A 4 reflects good organization and clarity.

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

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

No output schema exists, but the description fully explains the response structure (tracked[], expired[], snapshot_dates[]) with field details. It covers limits, data gaps, and edge cases. The tool is a read-only query, and the description provides all necessary information for an AI to use it correctly.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description restates defaults and ranges but adds no new semantic depth beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question of how long an edge has existed and if it's shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on time-series and decay analysis, not just current snapshots.

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 differentiate between a fresh wide edge and a stale one. It provides context about why an edge might persist (nobody willing to take the other side). However, it does not explicitly state when not to use or name alternatives, though sibling polymarket_edges is implied as the current-edge tool.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent. Description adds critical behavioral context beyond annotations: explains return fields (top_of_book, vwap_fill_price, slippage, etc.), walk-the-ladder behavior, basket forced_directional_risk, and thin_legs. 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 well-structured with clear sections (SINGLE-MARKET, BASKET, usage guidance). It is front-loaded with purpose and requirements. However, it is somewhat verbose; could be tightened slightly without losing clarity.

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

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

Given the tool's complexity (two modes, multiple return values, no output schema), the description is remarkably complete. It describes all relevant behaviors, risks, and outcomes (e.g., verdicts, thin legs, forced directional risk). No missing context.

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

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

Schema description coverage is 100%, but the description adds substantial value: clarifies default side logic for basket (auto from partition sum), explains size_usd interpretation for basket (settlement notional vs shares per leg), and distinguishes modes. The description goes beyond schema definitions.

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges by saying to use this before acting on their signals.

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

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

Explicit instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why theoretical overround may not be capturable and warns about partial fills converting arb to directional risk. Lacks explicit 'when not to use' but provides strong contextual 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?

Description extensively discloses behavior beyond annotations: explains response structure (raw probabilities, spreads, safety fields), compatibility conditions, and edge cases (unmatched bet shapes, temporal misalignment). No contradictions with annotations (readOnly, idempotent, non-destructive).

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

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

Description is well-structured with clear sections: core purpose, modes, response, safety fields. While lengthy, each sentence adds significant value. Minor redundancy could be trimmed, 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?

Description covers input, usage modes, response format, and detailed edge cases. Given no output schema, it provides complete guidance on what the tool returns and when results are reliable, compensating fully for the missing schema.

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

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

Schema already describes all three parameters with examples. Description adds context: explains that explicit tickers override topic-mapped sides, lists the 10 macro shortcuts, and gives concrete example inputs, 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?

Description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, with two modes (pre-mapped topics and explicit tickers). This distinguishes it from sibling tools like 'polymarket_arbitrage' which focus on single-venue arbitrage.

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

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

Description provides explicit guidance: explains two usage modes, conditions when spreads are meaningful (temporal alignment), and warns that most pre-mapped topics currently return compatibility warnings, implying when to use explicit tickers and tempering expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false; description adds scoping and the behavior of omitting the key, which complements but does not contradict annotations.

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

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

Two tight sentences, front-loaded with main action, no wasted words.

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

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

For a simple retrieval tool with one optional parameter and no output schema, the description fully explains usage, scoping, and behavior—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?

Description explains parameter 'key' beyond schema: omitting it lists all keys, adding actionable meaning to the schema's 100% coverage.

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

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

The description clearly states the tool retrieves a value by key or lists all keys, distinguishing it from siblings like 'remember' and 'forget'.

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

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

Explicitly advises when to use (look up context stored earlier) and how it scopes to an identifier, with mentions of paired tools 'remember' and 'forget'.

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

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

The description states that setting mark_read:true flags events as read, which is a mutation. However, annotations declare readOnlyHint: true, implying no writes. This is a direct contradiction, making the description misleading about the tool's behavior. Score 1 per rules.

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 3-4 sentences covering purpose, return fields, filtering, side effects, and alternative access. Each sentence adds useful information without redundancy. Some structure could be improved but it is 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 no output schema, the description explains the return format (source, citation_uri, raw payload). All 5 optional parameters are discussed. Annotations provide safety and idempotency. It is complete for a read-like tool, though pagination is not mentioned.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example for type ('sec_8k'), specifying 'ISO timestamp' for since, and noting default limit of 50. It also explains the effect of mark_read, which goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' with specific verb and resource. It distinguishes from siblings by focusing on alerts from a persisted feed, and mentions returns of source, citation_uri, and raw payload, making it distinct from other tools like list_subscriptions or recent_changes.

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

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

The description provides usage guidance by listing filtering options (type, since) and the mark_read flag. It suggests polling works fine and mentions an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts. However, it does not explicitly compare with sibling tools or state when not to use this tool.

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

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

Beyond annotations (readOnlyHint, etc.), the description discloses multi-source fan-out, fallback from GDELT to GNews, soft-failure for USPTO due to API sunset, and the return structure with citations. This adds substantial 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 front-loaded with use examples and structured logically, but it is somewhat lengthy. Every sentence contributes meaning, though minor trimming could improve conciseness.

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

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

Despite lacking an output schema, the description sufficiently explains return format (grouped changes, total count, citations) and sources. It covers all key aspects for a multi-source aggregation 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%, but the description adds value by explaining the since parameter formats (ISO date vs relative shorthand) and recommending typical values, and clarifying value accepts ticker or CIK. It reinforces the enum for type.

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

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

The description clearly defines the tool's purpose: fetching recent changes (filings, news, patents) for a company within a time window. It uses specific verbs like 'change feed' and distinguishes itself from the sibling tool entity_profile by explicitly stating when to use that alternative.

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 strong guidance with example queries and explicitly directs users to entity_profile for static profiles. It explains the parallel call nature but lacks explicit 'when not to use' or restrictions beyond the alternative suggestion.

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 show readOnlyHint=false (write operation), idempotentHint=true (safe to retry), destructiveHint=false. The description adds scoping by identifier, persistence vs. 24-hour retention. No contradictions. Could mention that overwriting same key replaces value, but not critical.

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 (3 sentences) and front-loaded with the primary purpose. Every sentence adds value: purpose, usage guidance, behavioral details, and a mention of companion tools. No wasted words.

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

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

Given no output schema, the description covers all necessary aspects: purpose, parameters, usage context, behavioral traits, and retention policy. It is complete for a simple key-value store tool.

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

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

Schema coverage is 100% with both parameters described. The description adds meaningful context beyond schema: examples of keys (subject_property, target_ticker, user_preference) and values (findings, addresses, preferences, notes), aiding correct usage.

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

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

The description clearly states the tool's purpose: to save data for reuse across conversations/sessions. It provides concrete examples (resolved ticker, target address, user preference, research subject) and distinguishes itself from sibling tools recall and forget, which are explicitly mentioned.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and provides specific examples. It also guides the agent to pair with recall for retrieval and forget for deletion, giving clear 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 readOnly=true, idempotent=true, and non-destructive. The description adds valuable behavioral details beyond annotations: graceful degradation if GLEIF/OpenFIGI are unavailable, internal cascading through multiple endpoints, and explicit labeling of identifiers with their source. 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 information-dense and front-loaded with examples, but it is relatively long (three paragraphs) and includes some redundancy (e.g., repeated mention of identifier sources). While no sentence is wasted, the length could be trimmed without losing clarity. Still well organized with key details first.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, no output schema), the description is remarkably complete. It explains what each entity type returns, mentions unresolved identifiers, graceful degradation, and internal cascading. The absence of an output schema is compensated by conceptual coverage of return contents.

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

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

With 100% schema description coverage, baseline is 3. The description greatly exceeds this by providing rich semantic context: for 'company' it explains the multi-source identity spine (CIK, ticker, LEI, FIGI) and accepted input formats (ticker, CIK, ISIN, name); for 'drug' it details RxNorm/RxCUI outputs and citation format. This adds meaning far beyond the schema's terse 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 opens with concrete example queries (ticker, CIK, LEI, RxCUI) that immediately clarify the tool's purpose: resolving user-spoken names to canonical identifiers. It clearly distinguishes from siblings by stating 'Use FIRST whenever you have a name but need an ID,' and the supported types ('company','drug') are explicitly defined with their resolution scopes.

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 contains a direct usage directive ('Use FIRST whenever you have a name but need an ID') and explains that the tool replaces 2-3 manual lookups, providing clear context. However, it does not explicitly enumerate when not to use this tool or suggest specific alternatives among the listed siblings (e.g., entity_profile for already-known IDs).

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and reinforced. Description adds behavioral details: probing each entity with ai_visibility_check, ranking, and returning score/confidence/signal density. 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?

Two sentences plus a parenthetical example. Every sentence adds value: first sentence describes action and process, second explains use case. Front-loaded and efficient.

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

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

Despite no output schema, description adequately describes the return (ranked list with score, confidence, signal density) and internal process. With 4 params, 1 required, and good annotations, 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% with clear descriptions for all 4 parameters. Description adds value by noting that the first entity is treated as the 'subject' for narrative, going beyond schema. Baseline 3 increased to 4 for this 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?

Description clearly states the tool compares AI visibility across multiple entities side-by-side, ranks by score, and identifies most/least recognized. It distinguishes from sibling ai_visibility_check (single entity) by specifying multi-entity comparison and competitive audit use case.

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 usefulness for competitive AI-marketing audits with a concrete question. While it doesn't explicitly list alternatives or when-not-to-use, the sibling list provides context and the description implies single-entity checks should use ai_visibility_check.

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: composite call, 5-30s delay on first measurement, partial failures with sources_failed list. Annotations indicate readOnly and idempotent, which are consistent.

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

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

The description is a single paragraph but dense with information. It front-loads the core purpose and adds necessary details efficiently. Slightly long but every sentence earns its place.

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

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

Given the complexity of a composite tool and no output schema, the description fully explains what the tool returns (summary block, advisories, links, alternatives) and handles partial failures. It is 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 description coverage is 100% and already explains the parameters. The description adds no new parameter-specific meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it is a composite check for npm packages, aggregating deps.dev and bundlephobia data. It uses specific verbs ('should I add') and distinguishes from sibling tools by specifying the ecosystem and the multi-source nature.

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 when to use ('is X safe / popular / small') and provides alternatives for other ecosystems. Also mentions timeout behavior and graceful degradation, guiding when to expect delays.

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, etc.), description discloses embedding model (BGE-base-en), chunking strategy (500-char windows, cosine), character limit (200K chars with truncation flag), and that passages include offsets for verification.

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 with front-loaded core action. Every sentence adds value, though could be slightly more compact without losing 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?

For a tool with no output schema, description fully explains what it does, how it works (embeddings, windowing), constraints (200K char limit), and return values (passages, offsets, scores). Also references complementary 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%, but description adds illustrative examples for 'text' and 'query', and specifies default/range for 'limit' (default 5, 1-20), enhancing clarity beyond schema alone.

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

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

Clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article) and distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains benefits (saves context, returns relevant passages with offsets). Pairs with a specific sibling for grounding.

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

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

The description adds substantial behavioral context beyond the annotations: requires Pipeworx OAuth account, idempotent (presumably), non-destructive, delivery channel details (e.g., SMS 10/day cap, webhook auto-disable after 10 failures, HMAC signing). 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 well-structured with clear sections (purpose, requirement, types, delivery) and every sentence adds value. However, it is somewhat long and could be slightly more concise by grouping examples, but overall it balances detail with readability.

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

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

Given the complexity of multiple subscription types, parameter options, and delivery channels, the description is remarkably complete. It covers auth requirements, type-specific parameters, delivery details, and return value. No output schema is needed as the description already states it returns a subscription ID.

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 100% coverage, and the description adds extensive detail: for type, it gives concrete examples (e.g., 'sec_8k' with `items`), for params it provides type-specific structures, and for delivery it explains verification, caps, and webhook secrets. This significantly augments 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 creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like unsubscribe and list_subscriptions by focusing on creation.

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

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

The description explicitly states when to use the tool (to set up alerts for live data events) and lists supported types with examples. It also mentions account requirements. However, it does not explicitly exclude alternative tools or scenarios where this tool is not appropriate.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds specific context about returning example questions with tool+argument shapes, and the optional topic parameter. It does not contradict annotations and adds useful behavioral detail.

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

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

The description is relatively long but well-structured: it starts with alternative phrasings, then explains purpose, then details. Every sentence adds value. Minor conciseness concern: could potentially be trimmed slightly, 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 that the tool has only one optional parameter, no output schema, and many siblings, the description is complete enough. It explains the use case, parameter options, and examples of what the tool returns. No significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the possible values for the topic parameter (finance, pharma, etc.) and their effect (focusing the results). This goes beyond the schema description which only lists 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?

The description clearly states it is the onboarding entry point for an agent that just connected, returning category-bucketed example questions. It distinguishes itself from siblings by explicitly recommending it as the first tool to use when the agent does not know what Pipeworx can do.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' This provides clear when-to-use guidance and differentiates from 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?

Discloses that the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. Adds behavioral detail beyond annotations (which already indicate non-destructive, idempotent).

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

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

Two efficient sentences: first states core action, second adds ownership and data lifetime details. No filler, every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, behavior (deactivation vs. deletion), and data availability. References sibling tool 'recent_alerts' for historical 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?

Input schema has 100% coverage with a clear description for the 'id' parameter. The description adds no extra parameter semantics beyond the schema, so baseline score of 3 is appropriate.

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

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

Clearly states the verb 'Cancel' and resource 'subscription by id'. Distinguishes from siblings by mentioning ownership enforcement and that historical events remain available via 'recent_alerts', differentiating from 'subscribe' and 'list_subscriptions'.

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

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

States when to use (cancel a subscription) and implies ownership constraint (you can only cancel your own). Does not explicitly mention alternatives or when not to use, but the context is clear given 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses critical behavioral nuances: the distinction between could_not_verify (check did not happen) and unsupported (no source exists), and the warning not to present could_not_verify as evidence. It also details the verification_error{stage,detail} payload and the citation format, adding substantial value over 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 dense but organized: examples lead, then usage guidance, then routing logic, then return-value detail, then critical caveats. Every sentence earns its place, though the length requires close reading. It is front-loaded with the most actionable 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 no output schema, the description compensates by fully describing the return tuple (verdict values, grounded/structured value with citation, reasoning) and the error-bearing fields. It also explains the routing pipeline and how this tool replaces multiple sequential calls, making it self-contained for a caller.

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 covers both parameters with 100% coverage, but the description adds extra semantic depth: tolerance_pct is explained as overriding claim-wording tolerance, with explicit guidance for hallucination detection (set 1-2). This enriches the schema beyond baseline.

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

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

The description uses specific verbs and resources: 'natural-language claim verification against authoritative sources' with example queries. It clearly distinguishes itself from sibling tools like check_password or compare_entities by focusing on factual claims, and it even specifies the company-financial vs. other-claims routing.

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 whenever the agent needs to check whether something a user said is factually correct', and describes two distinct usage paths (structured SEC EDGAR for company-financial claims, grounded pipeline for anything else). It does not mention alternatives or when not to use it, but the guidance is clear and concrete.

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