Pulsedive

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds valuable context beyond annotations: the free default model (Workers AI Llama-3.3-70b), that Anthropic requires a BYO key with direct payment, and the per-model return structure including score, confidence, signals, and raw_response plus a combined view.

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

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

The description is three sentences with no filler. It front-loads the core action and output (probe LLMs, score visibility), then covers defaults and return format, and ends with 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?

The description covers purpose, usage contexts, default behavior, cost considerations, and return structure even though there is no output schema. It does not mention limitations, rate limits, or edge cases, but the tool's complexity is moderate and the provided information is sufficient for an agent to select and invoke 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 baseline is 3. The description adds meaning by specifying the default model for `models` and the cost implication of `_apiKey` ('you pay Anthropic directly'), which enriches the bare schema descriptions. However, most parameter meaning is already well-documented in the schema itself.

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

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

The description uses a specific verb 'Probe' with a clear object (LLMs) and a measurable outcome (visibility score 0-100). It clearly differentiates from sibling tools like ask_pipeworx by focusing on LLM knowledge visibility rather than general Q&A, and lists concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring).

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 usage contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly name alternatives or give when-not-to-use guidance, but it does explain when to pass `_apiKey` (to also probe Anthropic) and the default model behavior, which is actionable guidance for choosing this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those: it routes to other tools, fills arguments, and returns structured answers with stable citation URIs. It does not describe failure modes or limitations, but the annotation coverage carries the safety profile.

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

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

The description is long but well-organized, front-loaded with the most important instruction ('PREFER OVER WEB SEARCH') and followed by scope, mechanism, triggers, examples, and alternatives. The domain list and examples earn their place because they help an agent decide when to route here. Slightly over-stuffed, but not padded.

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 routing tool with no output schema, the description is remarkably complete: it explains the return format (structured answer with citations), the breadth of coverage, when to use it, when not to use it, and which sibling to pick instead. The examples cover diverse domains and make invocation straightforward.

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

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

Schema description coverage is 100%, with all six properties clearly documented as aliases for the same `question` parameter. The description provides helpful examples and trigger phrases, but it does not add meaningfully beyond what the schema already states. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description clearly states what the tool does: it routes natural-language questions to one of 5,718 tools across 1,496 verified sources and returns structured answers with pipeworx:// citation URIs. It explicitly positions itself as 'PREFER OVER WEB SEARCH' and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: factual questions about real-world entities, events, numbers, current or historical data, and even cases where web search could also answer. It names alternatives and their specific conditions: ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad multi-part questions, and notes that breaking news is already handled by 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 the annotations, the description discloses that no candidate routing improvement is currently active, so the tool currently matches ask_pipeworx exactly. It also clarifies that this is a full working router with no fallback, and that it may have live experimental changes during candidate tests. This is exactly the kind of behavioral context an agent needs beyond readOnly/idempotent hints.

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

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

The description is well-structured and front-loaded with the beta identity, followed by current status, usage, and fallback behavior. Each sentence contributes useful context, though the exact date and tool count are slightly more detail than strictly necessary. Overall it is appropriately sized and scannable.

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

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

The description fully covers the beta caveats, current behavior, relationship to the stable tool, and operational expectations. Since there is no output schema, stating that the response shape is identical to ask_pipeworx is important and sufficient. An agent has everything needed to select and invoke this tool correctly.

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

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

The schema already provides 100% description coverage for all parameters, including aliases for 'question'. The description adds no new parameter-level meaning beyond saying it uses the same arguments as ask_pipeworx. Since the schema carries the load, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with identical tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling and explains that it is the experimental edge. This is specific, action-oriented, and leaves no ambiguity about what the 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 explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and explains that results are compared against the stable router to inform merges. It names the stable alternative and gives a clear use context. It does not explicitly say when not to use it, but the guidance is still strong.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description goes beyond these by disclosing the refusal behavior with specific refusal_reason values, the evidence/verbatim quote requirement, and the extra LLM call cost. 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 dense but well-structured: purpose, mechanism, success/refusal shapes, usage guidance, and cost comparison are all present. The list of refusal reasons and examples of high-stakes uses are justified. Slight redundancy in restating 'only what the tool result contains' after 'Hallucination-resistant' prevents a 5.

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

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

With no output schema, the description fully explains the return object and all possible refusal_reason values. It also covers when to use versus ask_pipeworx, the cost implication, and the natural-language input requirement. Nothing critical is missing for an agent 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 coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no new parameter semantics beyond 'Your question in natural language,' which the schema already fully captures. Baseline 3 is appropriate when 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 specific purpose: 'Hallucination-resistant answer mode for high-stakes reads' with explicit behavior—extracting answers only from tool results. It clearly distinguishes this tool from the sibling ask_pipeworx by emphasizing grounded, evidence-based answers rather than casual lookup.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. Also gives an alternative: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call, making the selection decision unambiguous.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses extensive behavioral traits: low-confidence matches short-circuit, closed markets return a specific status, wide spreads get a tradeability flag, 24h-move warnings, resolution-rule risk with cancellation_rule details, and news fallback fields. It also explicitly warns about EV-material void settlements, which is critical context not inferable from annotations.

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

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

The description is long but meticulously structured with bolded section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. Every section provides actionable details, but it is verbose and could be trimmed without losing core value. The first sentence front-loads the purpose, so it earns a 4 rather than a 5.

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

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

Given the tool's complexity (market resolution, classification, fan-out, safety mechanisms, response shape), the description covers all critical aspects: inputs, resolution confidence, parent-event extraction, news fallback, illiquidity warnings, closed/dead markets, and cancellation-rule risk. Even without an output schema, it fully describes the response envelope through the RESPONSE SHAPES and RESOLVER CONTRACT sections, making it complete for an agent to use correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description reinforces parameter semantics with examples for the market parameter (slug, URL, question text) and explains the depth/quick-thorough distinction, but does not add significant meaning beyond the schema for include_raw beyond restating the size implications. It adds no new parameter-specific semantics that are missing from the schema.

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

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

The description opens with a specific verb+resource+scope: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the tool resolves the market, classifies it, fans out to data packs, and returns an evidence packet with a market-vs-model comparison. It also distinguishes itself from sibling tools by targeting 'should I bet on X' use cases, which is unique among the listed research tools.

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

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

The description provides explicit when-to-use guidance: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives concrete fan-out examples for various bet types. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools like polymarket_edges or deep_research, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds rich behavioral detail: parallel execution, sorting by primary metric, handling of off-calendar fiscal years, and return of paired data with citation URIs. This goes well beyond the annotation safety profile.

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

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

The description is dense but every sentence contributes value: query triggers, usage preference, type-specific behavior, outcome sorting, and return format. It is well-structured with concrete examples and 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 explains return format (paired data + pipeworx:// citation URIs) and what data sources are used. It covers all essential aspects for an agent to invoke the tool correctly and interpret results, making it contextually complete for its complexity.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds meaning by explaining what each type retrieves (company financials from SEC EDGAR/XBRL, drug counts from FAERS) and provides examples of value formats (tickers vs drug names), plus sorting behavior tied to the 'largest'/'most' phrasing.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one parallel call. It lists specific query patterns and distinguishes itself from sequential single-entity lookups, making the purpose unmistakable.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and states it replaces 8–15 sequential lookups. This directly tells the agent when to use this tool versus alternatives, even though specific sibling tools aren't named.

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 a safe read-only, idempotent, open-world profile, and the description adds substantial non-obvious behavior beyond them: account/paywall requirements, 15–90s latency expectations, the never-invented gaps[] guarantee, always-fetchable citation_uri, semantic excerpting rather than head-truncation, contradictions[] scans, and hop fields. This fully compensates for the absence of an output schema and contradicts nothing in the annotations.

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

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

The description is long (~330 words) but unusually dense — nearly every clause carries a distinct fact, and it is front-loaded with the most critical gate (account requirement) before the mechanics. It loses a point only for mild redundancy: the second-hop iteration paragraph partially restates the schema's depth description, and ask_pipeworx is routed to three separate times.

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

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

With no output schema, the description carries the full burden of return-shape disclosure and succeeds: findings packet fields, gaps[], contradictions[], hop, citation_uri resolvability guarantees, and edge-case behavior for out-of-catalog topics. For a complex 2-param tool with 30+ siblings and an auth tier requirement, nothing an agent needs to call it correctly 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%, setting the baseline at 3; the description earns one point above baseline by adding the paid-plan requirement for depth:"thorough" (absent from the schema) and clarifying that the question parameter is intentionally expected to be broad/multi-part. Most parameter meaning still lives in the schema's detailed depth enum description, so it does not reach 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 a specific operation — grounded multi-source research across 1,496 named structured data sources in one call — with concrete mechanics: decomposition into facets, parallel routing to 5,718 tools, and a defined findings-packet return shape. It explicitly negates open-web search and explicitly contrasts with ask_pipeworx, so an agent can disambiguate it from siblings without opening any other schema.

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?

Gives three explicit routing rules: use ask_pipeworx when not signed in, use ask_pipeworx for a single lookup, and prefer ask_pipeworx for breaking/current-news topics where deep_research returns mostly empty gaps[]. It states the positive condition — broad/multi-part questions over structured data — with two concrete example queries. Nothing is left to inference.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavior: returns top-N tools with names, descriptions, and full input schemas with curated examples, and notes results are ready to call directly with no second schema lookup. This goes beyond annotations without contradicting them.

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

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

Three tightly written sentences: the first states the core function, the second explains return value and usage context, the third gives a clear priority directive. Every sentence earns its place with no redundancy or filler.

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

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

Despite no output schema, the description fully explains return values (tool names, descriptions, full input schemas with examples, ready-to-call). It also provides a concrete domain list, usage timing, and the 'call first' guidance. Combined with complete parameter schema and safety annotations, the tool is well-specified enough for an agent to select and invoke 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 description coverage is 100%, with all six parameters (query, q, task, limit, search, description) documented in the schema. The description's 'top-N' hints at the limit parameter and 'describing the data or task' maps to query, but it adds minimal meaning beyond the schema, so the 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 opens with a specific verb and resource: 'Find tools by describing the data or task,' then enumerates the covered domains (SEC filings, FDA drugs, FRED data, etc.). It clearly positions itself as a meta-discovery tool distinct from domain-specific siblings, reinforced by 'Call this FIRST when you have many tools available.'

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It implies when not to use (when you already have a specific tool in mind) but does not name alternative sibling tools.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is known. The description adds valuable behavioral context: parallel fan-out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific returned fields, a soft-fail for the patents API sunset, and a GDELT→GNews fallback. This goes well beyond the annotations and helps the agent set expectations for failure modes.

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

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

The description is dense with useful information: usage triggers, alternatives, sources, return fields, parameter examples, and fallback behavior. It is structured as a single flowing paragraph that front-loads the key 'what' and 'when to use' message. While it is long, it earns its length given the tool's complexity; the em-dash string of examples is particularly effective.

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

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

Given the tool has only 2 parameters and no output schema, the description carries the full burden of explaining return values. It enumerates the exact result payload (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI), and even notes the filing count and sort order. The only minor omission is explicit error behavior for invalid tickers, but the guidance to use resolve_entity mitigates that.

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 a baseline of 3 applies. The description restates the ticker/CIK format and name limitation, which reinforces the schema but adds little new meaning. It gives concrete examples ('AAPL', '0000320193') which are helpful for formatting, but the semantic burden is already fully carried by the input schema.

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

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

The description opens with concrete natural language triggers ('Tell me about X' / 'research Acme') and states the exact result: 'full cross-source profile of a US public company in ONE parallel call.' It clearly differentiates from siblings like deep_research, compare_entities, and resolve_entity, making the tool's scope unmistakable.

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

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

Explicit guidance is provided: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also names the sibling alternative 'resolve_entity' for name-based inputs, and warns that names are not supported. This directly tells the agent when to choose this tool and when to reach for another.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context like 'previously stored' and use cases, but does not disclose additional behavioral traits such as permanence or error handling. 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?

Three concise sentences; the first states the action, the second gives usage guidance, the third relates to sibling tools. Every sentence earns its place 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?

For a simple single-parameter delete tool with strong annotations, the description covers purpose, usage, and tool relationships. It does not describe return values or error behavior, but given simplicity and idempotency hint, this is a minor gap.

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

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

Schema has 100% coverage for the single 'key' parameter. The description repeats 'by key' but does not add further semantic detail beyond the schema's 'Memory key to delete.' 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 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from siblings by mentioning 'Pair with remember and recall' and specifying it clears data 'the agent saved earlier.'

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 use cases: 'when context is stale, the task is done, or you want to clear sensitive data.' These give clear context for when to use but do not explicitly state when not to use or name alternatives.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable process context: fetches the page, extracts title/description/key links, and emits the standard markdown format. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence earns its place by adding process, output format, or use cases. No fluffy or redundant 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?

For a simple 2-parameter tool with strong annotations and no output schema, the description is complete: it explains purpose, process, output format, and use cases. There are no obvious gaps that would hinder an agent from selecting and invoking the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details beyond what the schema already provides; it only loosely maps 'url' to 'any URL' and mentions key links. This does not elevate the score above baseline.

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

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

The description uses a specific verb 'Generate' and resource 'llms.txt file for any URL', clearly distinguishing the tool from siblings like ai_visibility_check. It also states the output format and use cases, making the purpose unmistakable.

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

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

The description lists explicit use cases: getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor. However, it does not explicitly name alternatives or state when not to use this tool, so it lacks the full 'when/when-not' guidance required for a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds value by specifying the exact return fields and the scope ('caller's active'), which goes beyond annotations. No contradiction found.

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

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

Two concise sentences, front-loaded with the primary purpose, followed by return fields and a practical use case. Every clause earns its place with no redundancy.

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

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

The tool is simple, has no output schema, but the description lists all return fields explicitly. It covers the primary purpose, use case, and parameter semantics via the schema. For a low-complexity list tool, this 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 coverage is 100% and the parameter's description is already clear ('Include cancelled subscriptions in the response (default false)'). The description does not refer to the parameter directly, but the schema handles it adequately, so 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 action ('List') and the resource ('the caller's active subscriptions'), and explicitly enumerates the return fields. It distinguishes itself from sibling tools by focusing on the caller's own subscriptions and the use case of reviewing before adding/canceling.

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 this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly mention when not to use it or name alternatives, but the guidance is clear and relevant.

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 (which only say readOnlyHint=false, etc.), the description discloses critical behavioral traits: filing returns a claim_token for later retrieval, rate-limited to 5 per identifier per day, free with no quota impact, and the team reads digests daily. These details are not inferable from the schema or annotations and greatly help the agent set expectations.

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

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

The description is longer than typical but every sentence carries necessary decision-supporting information. It is front-loaded with purpose and use cases, then exclusions, then token/rate-limit details. The structure is logical and no sentence is wasted; it earns its length.

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

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

Despite having no output schema, the description covers what the agent needs: return behavior (claim_token), how to follow up, constraints (rate limit, free), and what not to do. It also ties into the broader catalog by using sibling tool names and pack/tool context, making it complete for a feedback tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema: it explains that claim_token must be used with no other arguments, and instructs users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the message parameter's intended content. This extra context justifies a score above baseline.

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

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

The description opens with a specific verb-resource pair ('Tell the Pipeworx team') and states the exact purpose: 'something is broken, missing, or needs to exist.' It distinguishes this from sibling tools like ask_pipeworx and discover_tools by framing it as feedback reporting rather than querying or discovery, making its role 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 provides explicit when-to-use guidance: bug, feature/data_gap, praise. It also gives a clear when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead.' It even clarifies how to disambiguate ('Not sure? Pipeworx tool names are the ones this connection lists'), which is strong alternative guidance.

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

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

The description adds valuable behavioral details beyond annotations: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' These disclose data provenance, privacy, output shape, and caching behavior, far exceeding the readOnly/idempotent annotations.

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

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

The description is front-loaded with the core purpose, followed by bullet-like use cases and then technical details. It is slightly longer than strictly necessary but every sentence adds useful information, with no fluff.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully explains what is returned ('top tools, top packs, total call volume'), the aggregation source, caching, and privacy guarantees. It is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100% for the single 'window' parameter, so the baseline is 3. The description adds extra meaning by noting 'Cached 5min-1h depending on window,' which connects caching behavior to the selected parameter—value beyond the schema.

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

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

The description opens with a specific verb ('Returns') and a clear resource: 'the top tools, top packs, and total call volume' from Pipeworx. This clearly distinguishes it from siblings like discover_tools by focusing on aggregated agent call trends rather than tool discovery or Q&A.

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 three explicit 'Useful for' scenarios: discovering hot data sources, confirming canonical tools, and checking use-case alignment. This gives clear context on when to use it, though it does not explicitly mention alternative tools or when not to use it.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral details: it walks child markets, applies a Jaccard similarity threshold (≥0.30), filters placeholder partitions (>20%), and performs a fill check against live CLOB depth, explicitly warning 'do not trade it' when realizable_edge_pp ≤ 0. No contradiction with annotations found.

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

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

The description is long but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded core purpose. Every sentence contributes value, though the density could be slightly reduced without losing critical context. The structured format makes it navigable 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?

Despite no output schema, the description fully specifies return values (opportunities[] fields, partition_check fields) and behavior across all modes. It covers edge cases (low similarity, placeholder fractions, fill check), and references the custom sizing tool. For a complex tool with 0 required params, this is exceptionally 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 for event and topic, but the description adds substantial meaning: gives concrete slug examples, explains the internal processing (walks child markets, searches related events, flattens markets), and details outputs for each mode. This goes well beyond the schema's basic field explanations.

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

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

The description opens with a specific verb+resource+method: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between three modes (trending_scan, event, topic) and references a sibling tool (polymarket_fill_risk) for custom sizing, making its purpose unambiguous and well-differentiated.

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 when-to-use guidance for each mode: no args for trending scan, event mode for a specific market (recommended), topic mode for cross-event scanning. It also states an alternative tool for custom sizing ('For custom sizing use polymarket_fill_risk'), and explains the comparative advantage of cross-event mode over single-event mode.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses substantial behavior: 1h KV caching keyed on knobs, response segmentation, placeholder-slug filtering, rare-by-design gating, Fed bets excluded with an unreliability warning, and diagnostics for empty segments. It also warns that a 24h move alone may mean the edge is already priced in.

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 a clear purpose but becomes a dense wall of text with capitalized section headers and extensive implementation detail. While organized, it is overlong and partially repeats schema content (e.g., tradeable-edge knobs), so not 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?

There is no output schema, so the description carries the full burden of explaining return values. It covers top-level response segments (by_segment), the fields on every opportunity, fed_candidates/fed_note, and _diagnostics for understanding empty segments. This is complete for a complex discovery tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description groups parameters as 'TRADEABLE-EDGE KNOBS' and explains relationships like min_partition_leg_kelly vs min_kelly, but these details are already present in the schema descriptions. It adds conceptual framing but no fundamentally new parameter semantics.

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

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

The opening sentence states a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It clearly distinguishes from sibling tools like polymarket_arbitrage by framing this as Pipeworx-data-driven daily bet discovery rather than pure cross-market arbitrage.

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

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

The description explicitly positions the tool: 'Built for "what should I bet on today"' and says agents can discover opportunities without paging hundreds of markets. It explains when knobs should be adjusted (e.g., min_liquidity/max_spread_pp for realizable edge) but does not explicitly contrast against sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 safety. The description adds substantial behavioral context: snapshot write-trigger conditions (cache-miss), gaps meaning no scan, 60-day TTL, and that decay is computed from daily closes rather than intraday. It also explains the signed nature of edge_pp_net and what negative values mean, providing valuable transparency beyond annotation hints.

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

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

The description is structured with clear sections (purpose, Args, RESPONSE, LIMITS) and every sentence adds value. It packs detailed information without wasted words, making it dense but readable. The front-loading of the core question and the organized response format make it easy to parse.

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 (time-series, trends, decay, historical gaps) and the absence of an output schema, the description is remarkably complete. It enumerates response fields (tracked[], expired[], snapshot_dates[]), explains their semantics, and discloses important limitations (TTL, daily-only decay). No critical aspect seems 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% and includes defaults and ranges for both parameters. The description reinforces these details and adds interpretative context: 'days' is a lookback and 'window' selects the snapshot family, with examples of valid values. This helps the agent understand how parameters influence the returned time-series, going slightly beyond raw 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 states a specific purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a clear question ('how long has this edge existed and is it shrinking?') and distinguishes itself from the sibling polymarket_edges tool by focusing on time-series persistence and decay rather than current edges.

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

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

The description provides a clear use case: comparing fresh vs. old edges and understanding decay. It implies when to use this tool (when persistence/decay matters) but does not explicitly name alternatives or say when not to use it. The relationship to polymarket_edges is mentioned, which orients the user, but explicit exclusions or sibling comparisons are absent.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, making the safety profile clear. The description adds behavioral details beyond annotations: it walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, a verdict (clean|degraded|cannot_fill), identifies thin_legs, and warns about forced_directional_risk. This is valuable context not present in annotations, though it doesn't mention auth/rate-limit specifics.

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 long, the description is tightly structured with explicit sections: REQUIRES, SINGLE-MARKET, BASKET, and a final usage directive. Every clause adds information—modes, defaults, return fields, risk rationale—and there is no filler. It is front-loaded with the core purpose and uses typographic emphasis to separate concerns.

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, 4 params, no output schema), the description is comprehensive. It enumerates return fields for both modes, explains the interpretation of size_usd in basket mode, identifies thin_legs and forced_directional_risk, and even describes the dominant loss mode. This compensates for the lack of an output schema and makes the tool self-contained for agent decision-making.

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

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

Schema description coverage is 100%, with detailed descriptions for all four parameters, including mode-specific semantics (e.g., 'size_usd' clarified as 'max spend on buys, target proceeds on sells' and 'settlement notional' for basket). The description largely repeats these schema details (e.g., defaults, auto-side behavior) without adding novel parameter-level meaning, so the baseline of 3 applies.

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' which clearly states what the tool does. It also differentiates between single-market and basket modes and positions it as a pre-trade verification, distinguishing it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs when to use it: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (thin-book overround is not capturable, partial fills → unhedged directional risk) and contrasts single-market vs basket modes, giving clear context.

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

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

The description goes far beyond the readOnlyHint/openWorldHint/idempotentHint annotations by explaining the compatibility_warning and compatibility_codes[] fields, the rule that legs with unknown metric_type or match_subtype are never paired, skipped_unclassified, low_confidence_pairs[], temporal_alignment, and skipped_cross_type/subtype counters. It also explicitly warns that compatibility fields can be non-empty even when matched_pairs>0, which an agent must know to interpret results correctly. No contradiction with the annotations exists.

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 deliberately scaffolded with labels like TWO MODES, RESPONSE, SAFETY FIELDS, and Codes, and it front-loads the purpose before diving into edge-case flags. Every sentence carries operational weight, though a few caveats are repeated and the text sits at the upper edge of warranted length. It is well-structured but not maximally 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?

With no output schema, the description fully carries the burden of explaining return semantics: it covers leg-by-leg prices, top_spreads_pp, compatibility codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and dropped-comparison counters. It also provides realistic expectation-setting by noting that most pre-mapped topics return warnings and are not necessarily tradeable. Nothing important appears missing for an agent to decide whether and how to call the tool.

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

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

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds useful context that topic values are 'pre-mapped macro shortcuts' that auto-fetch the matching event and that explicit parameters override the topic-mapped side, but this does not substantially change the meaning of the schema. The bulk of the added semantic value is about output/response interpretation rather than the parameters themselves.

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?

Opens with a concrete definition: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It immediately clarifies the tool's scope and then enumerates two invocation modes, 'topic' shortcuts and explicit ticker/slug pairing, which makes the intended operation unmistakable. The cross-venue Kalshi/Polymarket focus also sets it apart from the other polymarket_* siblings.

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 two modes are explicitly contrasted: pre-mapped topic shortcuts versus explicit kalshi_event_ticker + polymarket_event_slug for custom pairings. It also warns that 'pre-mapped ≠ tradeable' and that most pre-mapped topics return compatibility warnings, which is important calibration. However, it never names a sibling alternative such as polymarket_arbitrage or states when this tool should not be used at all.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds context about the query language and shows an example call, but it does not disclose additional behavioral traits such as rate limits, authentication specifics, or what data is returned beyond 'indicators.' This is a moderate addition 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 plus an example, with the main purpose front-loaded. Every sentence adds value: the first defines the action, the second explains the query language, and the example illustrates usage. It is appropriately sized and well-structured.

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

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

For a search tool with 3 parameters and no output schema, the description is complete: it states what it searches, how the query language works, and provides an example. The annotations cover safety and idempotency, so no further details are essential. The description adequately covers the tool's purpose and usage 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%, so the baseline is 3. The description's example demonstrates how to use q, limit, and _apiKey, but the schema already provides descriptions and examples for each parameter. The description does not add significant new semantic meaning beyond what the schema offers.

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: 'Search Pulsedive threat DB with a query.' It specifies the resource (Pulsedive threat DB), the verb (Search), and the scope (indicators matching criteria like type, risk, feed, or threat). This effectively distinguishes it from sibling tools like pulsedive_indicator, which presumably looks up a single indicator.

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 communicates the intended use case ('find indicators matching criteria') and provides a concrete example, which implies when to use it. However, it does not explicitly mention when not to use it or suggest alternatives, such as using pulsedive_indicator for a known indicator. This leaves usage guidance at an implied level.

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 behavior. The description adds value by disclosing return content: 'risk level, contributing risk factors, associated threats, and intel feeds.' This goes beyond the annotations and gives the agent a clear picture of what the tool provides.

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 plus a compact example, front-loaded with the core question and then a clear statement of functionality. Every sentence contributes value, and the example is a helpful illustration without being verbose.

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

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

For a simple lookup tool with two parameters, strong annotations, and no output schema, the description covers the essential aspects: purpose, inputs, and output highlights. It does not explain error handling or edge cases, but given the tool's simplicity and good schema coverage, it is adequately 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% — both '_apiKey' and 'indicator' are well-described in the input schema. The description adds a usage example but no additional parameter semantics beyond what the schema already provides. This aligns with the baseline of 3 when the schema carries the parameter documentation burden.

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 direct question ('Is this IP/domain/URL/hash malicious?') and then clearly states the operation: 'Looks up an indicator of compromise (IOC) in Pulsedive and returns its risk level, contributing risk factors, associated threats, and intel feeds.' This is a specific verb+resource+output description that distinguishes the tool from siblings like pulsedive_explore.

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

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

The description clearly conveys when to use this tool: when you need to assess whether an IP, domain, URL, or hash is malicious and obtain risk details. It provides context and a usage example, but does not explicitly name alternatives or exclusions. However, the purpose is distinct enough that the context serves as clear usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful operational details: the behavior of omitting the key (list all), scoping to the agent's identifier, and the relationship to remember/forget. This is consistent with annotations and provides context beyond them.

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

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

The description is compact and well-structured: first the core action, then usage rationale, then scoping and pairing. Every sentence adds value with no filler, making it easy to scan.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers the main behavior, typical use cases, scope, and relationships with related tools. No critical information is missing for an agent to invoke 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% and the parameter 'key' is described as 'Memory key to retrieve (omit to list all keys)'. The description reinforces this and adds realistic examples like 'the user's target ticker, an address, prior research notes', which enriches understanding of what keys represent.

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 with specific verbs: 'Retrieve a value previously saved via remember, or list all saved keys'. It also distinguishes itself from sibling tools by mentioning 'remember' and 'forget' as complementary 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?

It provides usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It does not explicitly state when not to use it, but the pairing with 'remember' and 'forget' indirectly clarifies the workflow.

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 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which implies a state mutation. Annotations declare readOnlyHint=true and idempotentHint=true, which contradict this behavior. Therefore the description contradicts the annotations, scoring 1.

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

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

Four sentences, front-loaded with purpose, each sentence adds detail (return shape, filtering, mark_read, polling/HTTP alternative). No fluff.

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

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

Despite no output schema, the description explains that returned events carry source, citation_uri, and raw payload. It covers filtering, mark_read semantics, and polling/HTTP access, making it sufficient for the tool's simplicity. The mark_read contradiction slightly reduces completeness, but the description still provides a solid overview.

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 all 5 parameters with descriptions, satisfying baseline. The description enriches this by providing an example type ('sec_8k'), clarifying the 'since' ISO timestamp, and explaining mark_read's effect on future calls. This 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 opens with 'Pull fired events from your subscription feed,' a specific verb+resource that clearly establishes the tool's function. It distinguishes from siblings like list_subscriptions (which lists subscriptions, not alerts) and recent_changes. No ambiguity.

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

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

Provides clear context: it is for reading fired alerts from a persisted feed, supports polling, and offers an alternative HTTP endpoint for scripts/dashboards. Does not explicitly state when not to use or name sibling alternatives, so not a 5.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive, but the description adds substantial context: it fans out to SEC EDGAR, GDELT→GNews with a specific fallback condition, and notes USPTO soft-fails after a sunset. It also discloses the return shape (changes[], total_changes, citation URIs), which annotations do not cover.

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 yet well-organized, front-loading the purpose and then logically covering sources, parameter syntax, return structure, and an alternative tool. Every sentence contributes useful information 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?

Given the tool's complexity (multiple sources, fallback logic, parameter flexibility, and no output schema), the description thoroughly covers inputs, outputs, error behavior (soft-fail), and how to differentiate from a sibling tool. It leaves no critical gaps for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the since parameter's accepted formats (ISO date and relative shorthand) and recommending '30d' or '1m', which helps agents select a reasonable window. It also reinforces value as ticker or CIK, though the schema already states this.

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: a change feed for a company over a time window, answering queries like 'What's new with X'. It specifies the resource (company changes), the action (retrieve feed), and distinguishes itself from the sibling tool entity_profile by clarifying it provides the static profile instead.

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

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

It provides explicit when-to-use guidance through example questions and states a direct alternative: 'Use entity_profile instead when you want the static profile...'. It also describes fallback behavior across sources, which informs usage under rate limits or API unavailability.

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 meaningful details beyond the annotations: memory is scoped by user identifier, authenticated users get persistent memory, anonymous sessions retain data for 24 hours. This goes beyond the readOnlyHint, idempotentHint, and destructiveHint annotations, which are consistent with the tool's write-once/overwrite semantics. 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 four sentences, each earning its place: purpose, use case, storage details, and related tools. It is front-loaded with the core function and free of filler, making it easily parseable.

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

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

For a simple 2-parameter tool with no output schema, the description fully covers purpose, when to use, storage behavior, and related tools. It gives the agent everything needed to invoke the tool correctly without extraneous detail.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying 'key-value pair scoped by your identifier' and stating the value can be 'any text — findings, addresses, preferences, notes,' which reinforces the schema's parameter descriptions and adds usage 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 opens with 'Save data the agent will need to reuse later,' which is a specific verb+resource that clearly states the tool's function. It distinguishes itself from siblings by explicitly naming 'recall' and 'forget' as complementary tools, showing how it fits into the broader toolkit.

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 when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternatives and complementary tools ('Pair with recall to retrieve later, forget to delete'), giving the agent actionable decision criteria.

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

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

Even though annotations already declare readOnly/openWorld/idempotent/destructive hints, the description goes far beyond them: it discloses internal cascading through multiple endpoints, graceful degradation when GLEIF/OpenFIGI are unavailable, resolution of non-US issuers via ISIN-to-LEI mapping, the behavior of returning `figi_candidates` when ambiguous, and explicit `unresolved` output. This level of detail is highly valuable for an agent predicting side effects and edge cases.

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 segment earns its place: usage trigger, supported types, resolution details, edge cases, degradation behavior, and parameter guidance. While it could be tightened, the density of actionable information justifies the length. It is well-organized with clear sections ('SUPPORTED TYPES', 'LEI/FIGI enrichment'), making it scannable despite its size.

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 only 2 parameters and no output schema, the description provides a remarkably complete picture. It explains what outputs can be expected (identifiers with source labels, unresolved lists, candidate lists), how to handle ambiguous inputs, and what fallback behavior occurs. An agent is unlikely to need additional context to invoke this tool correctly, even among 30+ siblings in a large toolset.

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 at 100%, but the description adds critical semantic context beyond enum descriptions. It elaborates on the 'value' parameter with concrete examples per type (ticker, CIK, ISIN, name for company; brand/generic for drug), warns against including security-class words, clarifies that non-ticker instruments still resolve, and explains how ISIN maps to legal entities. This is exactly the kind of nuance an agent needs to call it correctly.

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

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

The description states a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers'. It lists concrete query examples and explicitly distinguishes itself from tools that consume those identifiers (e.g., 'other tools require as input'). The 'SUPPORTED TYPES' section further clarifies scope for company and drug entities, making it unmistakably distinct from siblings like 'entity_profile' or 'compare_entities'.

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

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

The description opens with explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also tells the agent what not to do via the `value` parameter instruction: 'never the question's full noun phrase'. It explains edge cases like non-equity instruments and what happens when a name matches multiple instruments, guiding the agent on expected behavior without needing to inspect schemas.

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

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

Annotations already declare readOnly, idempotent, and openWorld behavior. The description adds valuable behavioral context: it probes each entity using `ai_visibility_check`, ranks by score, and returns per-entity fields (score, confidence, signal density). This goes beyond the annotations by explaining mechanism and output format, so a 4 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 compact and front-loaded with the core action. Each sentence earns its place: the first states the primary function, the second explains the mechanism and output, and the third provides a concrete use case. The example quote is illustrative without being wordy. No filler or redundant phrasing.

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

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

Despite lacking an output schema, the description fully explains return values ('ranked list with score, confidence, signal density per entity'), usage ('competitive AI-marketing audits'), and behavior (probes with ai_visibility_check, ranks). With rich annotations and a 100% schema-coverage, this description gives an agent everything needed to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no extra parameter detail beyond what the schema already states—it mentions 'your brand + N competitors', which mirrors the `entities` parameter's existing description. Since the schema fully documents parameters and the description doesn't need to compensate, the baseline score of 3 stands.

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

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

The description opens with a specific verb+resource: 'Compare AI visibility across multiple entities side-by-side.' It further explains ranking and output ('ranks by score, surfaces which is most/least recognized'), which clearly distinguishes it from the single-entity sibling `ai_visibility_check`. The example use case('does Claude know about us as well as our competitors?')makes the purpose immediately accessible.

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' and the example scenario. It implies the tool is for comparing multiple entities rather than checking a single one, but it does not explicitly state when not to use it or name alternative tools. Since it gives clear situational guidance without explicit exclusions, it earns a 4.

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 read-only/idempotent annotations, the description discloses graceful degradation on partial failures, the 5-30s first-measurement delay from bundlephobia, and how timeouts are reported via sources_failed. This adds meaningful behavioral context not available in 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?

Despite being a single paragraph, every sentence delivers distinct value: purpose, use cases, return summary, ecosystem limitations, and failure behavior. It is structured logically with no filler, making it dense but 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?

With no output schema, the description fully details the returned summary fields, per-advisory info, links, alternative versions, and partial failure semantics. For a high-complexity tool external calls, this is thorough and complete.

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

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

Schema coverage is 100%, so the schema already describes both parameters and their defaults. The description reiterates the version default and scoped package acceptance without adding significant new semantic detail 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 explicitly states this is a composite check for evaluating whether to add an npm package, fanning out across deps.dev and bundlephobia. This clearly distinguishes it from sibling tools by specifying its exact scope and function.

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

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

Provides explicit use cases with quoted example queries, and explicitly excludes non-npm ecosystems by directing them to deps.dev:version directly. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds rich behavioral detail beyond those: it mentions output includes character offsets and similarity scores, uses BGE-base-en embeddings with cosine over 500-character overlapping windows, and discloses a 200K char cap with truncation and flagging. 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?

Three dense sentences with no fluff. Every sentence contributes: operation semantics, use-case justification, workflow pairing, and technical constraints. Structure is front-loaded with the core action and then dives into 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 has no output schema, the description compensates by explaining return values (passages with offsets and similarity scores). It also covers the operational workflow, performance characteristics, and truncation behavior, making it complete for accurate invocation and result interpretation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds context around parameter usage (e.g., passing text already pulled, natural-language query examples) but does not materially exceed the schema's descriptions for text, query, and limit. It is consistent but not enriching.

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 a specific verb-resource relationship: 'Semantic search INSIDE a fetched record.' It differentiates itself from siblings by emphasizing it operates on already-fetched text rather than a broader database, and explicitly references a companion tool (ask_pipeworx_grounded) to clarify its role.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides a pairing workflow ('Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages'), giving clear guidance on how it fits alongside 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 the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds rich behavioral detail: OAuth account requirement, always-on feed via recent_alerts/registry endpoint, optional email/SMS/webhook delivery, webhook signing secret returned once, auto-disable after 10 failing runs, and SMS 10/day cap. This goes far beyond what annotations indicate.

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 well-organized, using parenthetical examples to pack information. The first sentence states the core purpose, and subsequent sentences elaborate on types and delivery. While lengthy, it is efficient and every clause contributes value, though it could be slightly restructured for 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 tool's complexity (3 params, nested objects, 5 subscription types, multiple delivery options) and absence of an output schema, the description is remarkably complete. It covers prerequisites, return value, delivery mechanisms, webhook signing details, rate limits, and failure behavior, leaving little for the agent to guess.

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

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

The schema already provides 100% parameter coverage with detailed descriptions for type, params, and delivery. The description adds concrete examples (items:['5.02'], topic:'fed', series_id:'UNRATE') and clarifies constraints like verified phone for SMS and HTTPS-only webhooks, enhancing understanding beyond the schema.

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

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

The description clearly states the tool's function: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses a specific verb (create) and resource (subscription), and distinctly differentiates from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides clear context for usage: requires a Pipeworx OAuth account, lists supported subscription types with examples, and explains delivery channels. It does not explicitly state when not to use it or name alternative tools, but the context is clear enough to guide selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by explaining the output content (category-bucketed example questions with tool+argument shapes) and that it is drawn from the live catalog, which goes beyond annotation-only 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 a single, long sentence with examples and usage, but every clause adds essential information. It is front-loaded with example queries and the core purpose, and while somewhat dense, it avoids redundancy or filler.

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

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

Given the tool has no output schema, the description adequately explains the return type (category-bucketed example questions) and the parameter behavior. It also provides enough onboarding context for an agent. A perfect score would require additional detail on response structure or pagination, but overall it is complete for its purpose.

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

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

Schema description covers 100% of the parameter, listing the allowed values. The description supplements this with concrete examples ('finance', 'pharma', 'betting') and explicitly states that omitting `topic` gives a cross-category spread, adding meaning beyond the schema.

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

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

The description clearly states the tool's purpose as 'the onboarding entry point' that returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('returns', 'call') and distinguishes itself from siblings by instructing to 'Use this FIRST' when unsure of Pipeworx capabilities.

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

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

Explicitly says when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also clarifies the optional `topic` parameter usage. However, it does not explicitly name alternative tools like discover_tools, so it lacks an explicit exclusionary comparison, earning a 4 rather than a 5.

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

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

Annotations already mark it as non-destructive and non-read-only, but the description adds crucial details: ownership enforcement and that the row is deactivated rather than deleted. This clarifies the actual effect and preserves historical data, going beyond the annotations. No contradiction found.

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 the primary action, then behavioral caveats. Every sentence provides essential information without redundancy.

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

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

With one parameter, comprehensive annotations, and no output schema, the description covers purpose, ownership constraint, and post-cancellation behavior. It is sufficiently complete for the tool's simplicity.

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

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

The schema fully documents the single 'id' parameter, including its type and origin from subscribe. The description only says 'by id,' adding no new semantics beyond the schema. Baseline of 3 applies given 100% schema coverage.

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

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

The description opens with 'Cancel a subscription by id,' providing a specific verb and resource. It clearly distinguishes from sibling tools like subscribe and list_subscriptions, and clarifies the action is a cancellation, not deletion.

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

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

It states ownership is enforced, giving a clear condition for when the tool can be used. It mentions recent_alerts as a way to access historical events, implying an alternative but doesn't explicitly compare to other subscription tools. Overall, it gives solid contextual guidance but lacks explicit when-to-use phrasing.

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

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

The description discloses key behaviors beyond the annotations: the special meaning of could_not_verify (with verification_error) and its non-evidentiary nature, the unsupported fallback, and the automatic routing. These are important caveats that the annotations do not cover, making the tool's behavior transparent.

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

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

The description is front-loaded with user-facing trigger phrases and use cases, then logically progresses through routing, output, and critical callers' caveats. Every sentence adds necessary information for correct invocation, and the structure makes it easy to scan.

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

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

Since there is no output schema, the description compensates by fully explaining the return shape (verdicts, value with citation, reasoning) and the critical distinction between could_not_verify and unsupported. Combined with rich annotations and schema coverage, the description leaves no major operational 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?

The input schema already provides 100% descriptive coverage for both parameters, including the purpose and default behavior of tolerance_pct. The description adds behavioral context about exact percent-delta math but does not materially enhance parameter semantics beyond the schema, so the baseline 3 applies.

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

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

The description clearly defines the tool as conducting natural-language claim verification against authoritative sources, using explicit verb 'verify' and listing exact verdicts. It also distinguishes from sibling tools by noting it replaces 4–6 sequential calls, making its scope unmistakable.

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

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

Explicitly states the trigger: whenever the agent needs to check whether something a user said is factually correct. It details routing logic for company-financial vs. other claims, giving clear context. However, it does not explicitly state when NOT to use it (e.g., for open-ended research), so it lacks a full exclusion boundary.

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