Market Recap

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful context: default model is free, passing _apiKey incurs direct cost to the user, and it explains the return structure. This goes beyond the annotations and clarifies financial implications.

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, front-loaded with the primary action, and every sentence provides useful information. No fluff or repetition.

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

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

With no output schema, the description compensates by listing the exact return fields ({score, confidence, signals, raw_response} + combined view). It also covers parameter defaults, cost implications, and use cases, making the tool understandable without additional documentation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the specific model name (Llama-3.3-70b) and emphasizes that default is free, which is more specific than the schema's 'workers-ai (free default)'. It reinforces the relationship between _apiKey and anthropic model.

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') and resource ('one or more LLMs'), and clearly states the output (visibility score 0-100 per model). It distinguishes itself from sibling tools by focusing on probing LLM knowledge for any entity, unlike tools like scan_competitor_ai_presence or validate_claim.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model and optional Anthropic key. However, it does not explicitly contrast with alternative tools or state when not to use this tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses operational behavior: it routes questions, fills arguments, provides stable pipeworx:// citation URIs, and is fast ('one fast call'). This adds useful context about how it works without contradicting annotations.

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

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

The description is long but well-structured, front-loaded with the key instruction 'PREFER OVER WEB SEARCH', followed by concrete triggers, examples, and alternative tools. Every sentence adds value, though it could be trimmed without losing essential guidance.

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

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

For a complex router tool with no output schema, the description covers purpose, input examples, return format (structured answer with citation URIs), and usage boundaries. It is fully adequate for an agent to select and invoke correctly.

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

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

Schema coverage is 100% (with 'question' and five aliases fully described), so baseline is 3. The description adds examples of question content but does not enrich parameter meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: it is a default entry point for factual questions, routing to 5,521 tools across 1,452 sources and returning structured answers with citation URIs. It uses specific verbs like 'routes', 'fills', and 'returns', 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 provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and 'START HERE for most questions'. It also gives clear alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus notes for breaking news.

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

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

Annotations provide read-only, open-world, and idempotent hints, and the description adds valuable context beyond them: it explains the beta nature, that no candidate is currently active, and that it falls back to nothing — confirming it's a fully functional router, not a stub. This clarifies behavior and potential risks of using an experimental edge.

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 identity and quickly moves to usage guidance. It is somewhat verbose, repeating 'same' twice and including parenthetical details, but every sentence contributes meaning (identity, current state, usage, comparison purpose, fallback behavior). It could be tightened, but it remains well-structured and readable.

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

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

Given that this is a simple router tool with no output schema, the description sufficiently explains the tool's purpose, current operational state, and how to use it. It does not elaborate on the return format, but the mention of 'same response shape' as ask_pipeworx covers this for an agent familiar with the sibling. The description is complete enough for safe invocation.

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

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

Schema coverage is 100%, with each parameter (question and its aliases) described. The description adds no additional parameter-level detail beyond saying 'same arguments' as ask_pipeworx. Since the schema covers everything, a baseline score of 3 is appropriate; the description only mildly reinforces the parameter semantics.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that processes questions through 5,521 tools. It distinguishes itself from the stable ask_pipeworx by noting candidate routing improvements, but does not explicitly differentiate from ask_pipeworx_grounded. The verb 'ask' plus resource 'pipeworx' is specific enough.

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 states 'Use it exactly like ask_pipeworx when you want the newest routing,' giving explicit when-to-use guidance. It also mentions results are compared against the stable router to decide merges, implying it's for experimental use. However, it does not explicitly mention alternatives like ask_pipeworx_grounded or state when not to use it (e.g., when stability is preferred).

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses the exact return structure, including success and refusal cases with specific refusal_reason values. It also reveals the extra LLM call cost, offering valuable behavioral context not captured 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 two sentences, starting with a powerful, informative opener. The second sentence is dense with critical details (return shape, refusal reasons, cost trade-off), but remains efficient and well-structured. Could be split for readability, but no waste.

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

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

Given the tool's complexity and absence of an output schema, the description thoroughly covers return format, error behavior, and usage context. It clearly distinguishes from siblings and provides all necessary information for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question'. The tool description adds no new parameter-specific semantics but doesn't need to; it relies on the schema. Baseline 3 is appropriate as the schema carries the weight.

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 "Hallucination-resistant answer mode for high-stakes reads," which clearly states the tool's purpose. It further differentiates from the sibling ask_pipeworx by emphasizing evidence extraction and explicit refusal behavior, making the tool's function 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 usage guidance is provided: "Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts" and "prefer ask_pipeworx for casual lookups." This directly addresses when to use this tool versus the alternative, satisfying the dimension fully.

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

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

Despite strong annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds substantial behavior: resolver confidence contract (low/medium/high/none), blocking statuses (low_confidence_match, market_closed_or_inactive), 24h-move warning, illiquid_wide_spread flag, GDELT 429 fallback mechanics, and cancellation-rule risk. No contradiction with annotations.

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

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

The description is exceptionally long but well-structured with section headers, bolded labels, and dense, relevant details. It is front-loaded with the core purpose and input formats. Some redundancy exists (e.g., closed-market behavior described twice), but each section earns its place for a tool with this complexity.

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

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

Given the lack of an output schema and the tool's complexity, the description is remarkably complete: it details input normalization, classifier list, fan-out examples, response shapes, resolver contract, parent-event extraction, news fallback, safety statuses, and cancellation-rule risk. There is little left for an 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?

Schema coverage is 100%, so baseline is 3; the description adds value by explaining the market parameter's flexible input forms (slug/URL/question text), depth quick vs thorough semantics, and include_raw size implications. The fan-out examples also clarify how parameter values map to different data sources.

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 specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly defines accepted inputs (slug, URL, question text) and describes the pipeline (resolve, classify, fan out), distinguishing itself from sibling research tools via its unique market-vs-model comparison and category-specific data packs.

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 ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), which is clear contextual guidance. However, it does not name alternative tools or explicitly state when not to use this tool, so it falls short of the highest bar.

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 specific data sources (SEC EDGAR/XBRL, FAERS), metrics (revenue, net income, cash, long-term debt, adverse-event counts), edge-case handling (off-calendar fiscal years), sorting behavior, and return format (paired data + citation URIs). This goes far beyond the annotations' read-only 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 dense but well-structured, opening with common user phrasings, then stating core function, preference rule, and per-type details. Every sentence provides actionable 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?

Given no output schema, the description fully covers return values (paired data + citation URIs), sorting order, entity count limits, and data sources. For a comparison tool with 2 parameters, this is complete and leaves no critical ambiguity.

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

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

Despite full schema coverage, the description adds deep semantic value by explaining what each type ('company' or 'drug') returns, including data metrics and fiscal year handling. This clarifies the enum values beyond the schema, compensating for no output 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 it performs side-by-side comparison of 2–5 companies or drugs in a single call, with specific examples of user intent. It distinguishes this from sequential single-pack lookups by emphasizing 'ALWAYS PREFER', making the tool's 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?

It provides explicit guidance to prefer this tool over sequential lookups when comparing entities and lists trigger phrases. However, it does not name alternative tools like entity_profile for single-entity lookups, so the exclusions are less explicit than the highest bar.

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 readOnlyHint, openWorldHint, and idempotentHint, the description adds substantial non-obvious behavioral context: account/paid-tier requirements, latency ranges, parallel decomposition across 5,521 tools, gaps[] never invented, contradictions[], and citation_uri guarantee fetchability. No annotation contradiction 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?

Though long, the description is front-loaded with the critical account requirement and every sentence adds meaningful guidance (use cases, exclusions, latency, return semantics, citation resolvability). There is no filler or repetition; the length is proportional to the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet, verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field, and citation_uri semantics. It also sets expectations around latency and excerpting behavior, making the tool's behavior fully understandable.

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 100% of parameter descriptions, including depth enum semantics, so the baseline is 3. The description adds value by linking depth to hop behavior (gap recovery, contradiction scan, paid plan requirement) and clarifying that broad/multi-part questions are acceptable, which justifies a 4.

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

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

The description names a specific verb and resource: "grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources" in ONE call, and explicitly contrasts itself with open-web search and ask_pipeworx. This clearly differentiates it from siblings and states what the tool accomplishes.

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 with examples ("compare X and Y's regulatory + financial exposure"), and explicit when-not-to-use instructions: "For a single lookup use ask_pipeworx" and "For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx." It also provides account-level guidance: signed-out users should use ask_pipeworx.

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 valuable behavioral detail beyond the annotations: it explicitly states the return format (top-N tools with names, descriptions, and full schemas) and the 'ready to call directly, no second schema lookup needed' property, giving the agent a clear expectation of what happens.

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 long, front-loaded with the core purpose, followed by a domain list and return behavior. Every sentence serves a purpose; no redundant or filler 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?

Despite lacking an output schema, the description fully explains the return value (top-N tools with schemas and examples) and provides strong usage context. It is self-sufficient for an agent to decide when to invoke this tool and what to expect.

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 clear descriptions for all parameters including aliases. The description adds domain examples for query formulation but does not elaborate on individual parameter semantics. Baseline 3 is appropriate since the schema handles 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 the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It also enumerates concrete data domains (SEC filings, FDA drugs, etc.), which distinguishes it from sibling tools that perform specific research tasks.

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

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

The description provides explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when not to use it (when you already have a specific answer) without needing to 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 this as a safe, read-only, idempotent operation. The description adds valuable behavioral details beyond annotations: it fans out in parallel, lists specific return fields, and discloses that the USPTO patents source 'sunset May 2025 — soft-fails until reactivated' and that news uses a GDELT→GNews fallback. It doesn't mention rate limits or auth, but the added context is strong.

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 each sentence carries weight. It front-loads with example prompts, then states the core purpose, usage preference, return details, and parameter constraints. It's more verbose than ideal, but justified given the tool's complexity and multiple data sources.

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 compensates by enumerating the return structure: cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, and LEI. It also covers source behaviors (parallel fan-out, fallbacks, soft-fail) and input formatting, making it nearly complete for an agent to use effectively.

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

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

The input schema already covers 100% of parameters with descriptions for both 'type' and 'value'. The description reinforces with concrete examples ('AAPL', '0000320193') and reiterates the name limitation, but doesn't add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description is exceptionally clear: it states the tool produces 'a full cross-source profile of a US public company in ONE parallel call' and provides concrete example queries. It also distinguishes itself from chained single-pack lookups and from sibling tools like resolve_entity, making its purpose unambiguous.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view,' and clearly notes that names are not supported, directing the agent to use resolve_entity first. This provides both 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 destructive and idempotent behavior, and the description adds context about clearing sensitive data and the tool's role in the memory lifecycle. It doesn't contradict annotations and provides extra behavioral context beyond 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 three sentences, front-loaded with the core action, and includes only necessary guidance 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?

For a simple one-parameter destructive tool with annotations covering safety and idempotency, the description provides the necessary usage context and role within the tool family. No output schema is needed, and the description 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?

The schema has full coverage for the single 'key' parameter with description 'Memory key to delete,' and the description restates it without adding new details such as format or validation rules. Therefore the description adds no significant value beyond the schema.

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

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

The description clearly states the tool deletes a memory by key, using the specific verb 'Delete' and resource 'memory.' It also differentiates from siblings by referencing the 'remember and recall' trio, making its role as the deletion counterpart explicit.

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

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

It explicitly provides usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall, implying alternatives for storage and retrieval.

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

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

Adds behavioral details beyond annotations by describing the fetch-extract-emit workflow and the output as a single text blob. Annotations already cover readOnly/idempotent/destructive hints, so the description supplements rather than contradicts 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 sentences, front-loaded with purpose, then process, then use cases. Every sentence contributes value with no fluff or redundancy.

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

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

Even without an output schema, the description explains the return format ('single text blob'), the standard llms.txt format, and practical use cases. With only 2 simple parameters, the description is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and already describes both parameters with meaning. The description only rephrases 'any URL' and does not add new parameter semantics, 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?

Clearly states it generates a production-ready llms.txt file for any URL, with specific actions (fetches, extracts title/description/key links) and emits standard markdown format. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 'Useful for' scenarios (client indexing, drafting for own project, competitor auditing) that frame when to apply the tool. Does not explicitly mention alternatives or when-not-to-use, but the use cases give 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?

Annotations already declare readOnly and idempotent, but the description adds important context: keyless access (Yahoo Finance), return fields (current price, previous close, change, daily % change), and accepted symbol formats (^, =X). 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?

The description is dense but well-structured: it opens with the key usage directive, then details supported symbols and return data, and closes with an alternative tool. Every sentence contributes useful information; no filler or redundancy.

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

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

With an output schema present, the description need not detail return values. It fully covers input semantics, symbol formats, and tool placement versus siblings. For a simple one-parameter tool, this is complete and actionable.

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

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

Schema already covers the single parameter with 100% description coverage, but the description enhances meaning with concrete symbol examples (^GSPC, AAPL, BTC-USD, EURUSD=X) and notes that comma-separated strings are accepted. This adds practical guidance 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 states a specific verb+resource ('get current quotes by symbol') and clearly distinguishes from siblings like web search and market_snapshot. It enumerates asset classes (stocks, indices, crypto, FX, commodities) and provides concrete examples, making the tool's purpose unambiguous.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' for current quotes, and names market_snapshot as the alternative for a broader market recap. It also gives example queries and clarifies symbol requirements, leaving no doubt when to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds value by specifying the exact return fields and clarifying that only active subscriptions are listed by default (with inactive optionally included), which complements 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 two sentences: the first front-loads the action and return fields, the second gives usage context. Every detail earns its place, with no redundant or vague language.

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

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

For a simple list tool with one optional parameter, the description covers the return format explicitly, the default active-only scope, and the intended use cases. Combined with the rich annotations (read-only, idempotent, non-destructive), it is fully self-sufficient for an agent to select and invoke correctly.

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

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

The input schema has 100% coverage for the single parameter include_inactive, with its own description. The tool description's phrase 'active subscriptions' implicitly reinforces the default behavior but does not add meaning beyond what the schema already provides, 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 uses the specific verb 'List' with resource 'subscriptions' and clearly scopes to 'the caller's active subscriptions,' distinguishing it from sibling tools like subscribe and unsubscribe. The return fields are explicitly enumerated, leaving 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 gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This clearly indicates when to use the tool, though it doesn't explicitly mention alternatives or when-not-to-use, 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 indicate read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable context by stating it is 'Live', returns 'structured numbers', and is 'Keyless (Yahoo Finance)', which discloses the data source and auth requirement. It does not contradict 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 efficiently structured with a front-loaded summary, then defaults, usage, output type, and auth note. Every sentence adds value, and the dense but organized listing of asset classes avoids unnecessary words.

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

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

Given the tool has only one optional parameter with full enum documentation, the description covers the critical context: what the tool returns, the default scope, how to narrow by region, the output format (structured numbers), and the fact that no key is required. No output schema exists, but the narrative description sufficiently explains the return value for an agent.

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

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

Schema coverage is 100% and the region parameter is fully described with an enum. The description goes beyond the schema by detailing the default headline composition (Asia + Europe + US futures + 10Y + DXY + oil + gold + BTC) and framing region as a way to 'drill into one group,' adding practical meaning to the parameter.

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

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

The description clearly states the tool provides a live market snapshot for a recap, listing the exact asset classes covered (major indices, Treasury yields, FX, commodities, crypto) and how data is grouped by region. This distinguishes it from sibling tools like get_quotes or top_movers by focusing on a curated, group-level overview rather than individual quotes or movers.

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

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

The description gives clear context for when this tool is appropriate ('what happened in markets' recap), explains the default headline behavior, and instructs to 'Use region to drill into one group.' It does not explicitly mention when not to use it or suggest alternatives, but the default and region guidance provide solid usage direction.

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

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

Discloses rate limiting (5 per identifier per day), the claim_token return-and-redeem flow, that the team reads digests daily, and that feedback doesn't count against quota. These are material behaviors not captured in the minimal 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 fairly long but information-dense; each sentence adds practical guidance. Minor redundancy (the 'ONLY for tools served by this connection' point is repeated) 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?

For a 4-parameter tool with nested context and no output schema, the description covers purpose, usage conditions, exclusions, token mechanics, rate limits, and content guidance. It fully compensates for the lack of annotations and output schema.

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

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

Schema descriptions already cover all parameters at 100%. The description adds valuable semantics on claim_token usage ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) with no other arguments') and advises describing issues in terms of Pipeworx tools/packs, which aids correct parameter filling.

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

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

The description opens with a clear verb-object statement ('Tell the Pipeworx team something is broken, missing, or needs to exist') and distinguishes this from all sibling research tools by focusing solely on feedback about Pipeworx itself.

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 (bug, feature/data_gap, praise) and when not to (tools from other MCP servers), including a fallback instruction to file with that server instead. This is exemplary when-to-use guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive. The description goes beyond by disclosing that it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on the window. These are meaningful behavioral traits not present 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 well-structured and efficient. It front-loads the core purpose, then lists return items and use cases in a scannable format. Every sentence provides value, and there is 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?

For a tool with one optional parameter and no output schema, the description is very complete. It explains what the tool returns (top tools, top packs, total call volume, and the aggregation details), gives use cases, and discloses caching and PII behavior. Nothing essential is missing.

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

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

The single parameter 'window' is fully documented in the schema with an enum and a clear description of how short vs. long windows behave. The tool description only echoes the available windows and adds a caching note, which is more about behavior than parameter meaning. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description opens with a specific, action-oriented statement: 'What other AI agents are calling on Pipeworx right now.' It then details exactly what it returns (top tools, top packs, total call volume) and the time windows. This clearly distinguishes it from siblings like discover_tools and market_snapshot.

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 an explicit 'Useful for' list with three concrete use cases (discovering hot data sources, confirming canonical tool choice, checking alignment with agent needs). This gives clear when-to-use guidance, but it does not mention when not to use the tool or alternative tools, 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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals rich behavioral detail: the 3pp threshold for signals, placeholder filtering (>20% yields null), Jaccard similarity anchor, and the fill check against live CLOB depth. This gives the agent a strong sense of what happens internally and when not to act.

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

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

The description is long but every sentence earns its place, covering modes, filters, response shape, and trade advisories. It is front-loaded with the core purpose and uses clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) to structure complex information without being redundant.

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 fully compensates by describing the response structure (opportunities[], partition_check fields). It also explains failure modes like skipped_low_similarity and placeholders_filtered, making the tool's behavior comprehensive 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?

Although schema coverage is 100%, the description significantly enriches parameter meaning: it explains that 'event' accepts slugs or full URLs, defines 'topic' as a seed question, and describes the resulting behavior (monotonicity check, partition check). The no-args mode is also covered, which the schema omits entirely.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk by focusing on arbitrage and explicitly naming the fill-risk tool for custom sizing.

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: no args for trending_scan, 'event' for a specific market, 'topic' for cross-event scanning, and even says 'For custom sizing use polymarket_fill_risk.' It also warns against trading when realizable_edge_pp ≤ 0, which is a clear exclusion condition.

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

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

The description is exceptionally transparent, detailing model families, response segments, diagnostics, caching, slippage assumptions, Kelly caps, and a 24h-move warning. It also explains conditions under which opportunities are dropped (placeholder slugs, low liquidity) and why segments might be empty. This goes far beyond the annotations, providing deep behavioral insight.

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 dense wall of text, including non-essential details like per-sport alpha values, placeholder slug patterns, and funnel counters. While it uses uppercase labels to organize sections, it is not concise and could overwhelm an agent. A more focused summary would be more 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's complexity (9 parameters, multiple model families, no output schema), the description covers all necessary aspects: response top-level structure, field meanings, filter knobs, diagnostics, and limitations. It gives an agent enough context to understand expected outputs and configure the tool appropriately.

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

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

Although schema coverage is 100%, the description adds critical parameter context: it explains why min_kelly doesn't apply to partition arbs, how min_liquidity/max_spread_pp act as tradeable-edge filters, and how slippage_pp affects ranking. This is genuine added meaning that aids correct parameter selection.

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

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

The description opens with a specific, action-oriented statement: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly identifies the tool's function and differentiates it from siblings like polymarket_arbitrage or polymarket_edge_tracker by emphasizing the Pipeworx data comparison and daily opportunity discovery.

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 phrase 'Built for "what should I bet on today"' gives a clear intended use case, and the note that Fed bets are excluded due to unreliable signals provides a concrete limitation. However, it does not explicitly mention alternative tools for other scenarios, so it stops short of full 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, idempotentHint, and non-destructive behavior. The description adds valuable behavioral context: 60-day snapshot TTL, snapshots only written on cache-miss (explaining data gaps), and that decay numbers are based on daily closes, not intraday. This goes well beyond what annotations provide.

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

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

The description is well-structured with clear sections for purpose, arguments, response, and limitations. It is front-loaded with the core question it answers, and every sentence carries relevant information without redundancy. Despite its length, it earns its size given the tool's complexity.

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

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

There is no output schema, so the description fully explains the return structure: tracked[] with time-series, trend, decay metrics; expired[] with lifespan; and snapshot_dates[]. It also covers limitations like TTL and data gaps. This is complete for a telemetry tool with this level of nuance.

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

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

Schema coverage is 100% for both parameters, so the baseline is 3. The description adds minimal extra meaning ('snapshot family' for window) and slightly under-describes days by omitting the clamp minimum of 2 that appears in the schema. It does not meaningfully compensate or add value beyond the schema.

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

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

The description clearly states the tool's function: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers a specific question about edge longevity and decay. It distinguishes itself from the sibling polymarket_edges by focusing on historical persistence 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 clear context for when to use the tool, emphasizing the difference between a fresh wide edge and a 3-week-old wide edge. However, it does not explicitly mention alternatives or when NOT to use it, 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?

Even though annotations already declare readOnly/idempotent/non-destructive behavior, the description adds substantial behavioral detail: it walks the order-book ladder, returns verdicts (clean|degraded|cannot_fill), and explains that partial basket fills turn an arb into unhedged directional risk. This goes well beyond the annotations and paints a clear picture of what the tool does and its limitations.

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 dense, and it uses clear SINGLE-MARKET/BASKET sectioning and all-caps reminders for critical information. While every sentence adds value, the length and emphasis patterns make it slightly less scannable than an ideal description; a light reorganization into bullets would improve readability without losing 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?

With no output schema, the description fully compensates by enumerating the returned fields per mode (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict; theoretical_sum, capture_ratio, profit_usd, thin_legs[], etc.). It also covers the critical edge cases and risk context, making it self-sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 100%, but the description goes far beyond the schema by explaining mode-dependent semantics: market vs event modes, how side and size_usd are interpreted differently in single-market vs basket mode, and the default/clamping behavior. It also clarifies the mutual-exclusivity requirement, which the schema does not enforce.

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 'Realizable-vs-theoretical edge check against live CLOB order-book depth' gives a specific verb and resource, and the tool is clearly distinguished from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk/execution quality. The description also states its exact role in the workflow, removing any ambiguity about purpose.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', providing concrete triggers. It also explains when not to rely on theoretical edges and why partial basket fills are dangerous, which is strong usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description goes far beyond by explaining safety fields, compatibility_warning conditions, temporal_alignment, and skipped_cross_type/subtype counters. It clearly discloses when spreads are meaningless (aligned:false) and how the tool handles non-equivalent bet shapes.

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

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

The description is lengthy and dense, but every sentence contributes useful information: purpose, behavioral nuances, response fields, and safety warnings. It is front-loaded with the core purpose. While not as succinct as the two-sentence gold standard, the complexity of the tool justifies the length.

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

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

Given there is no output schema, the description thoroughly explains the response structure: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It covers edge cases and caveats, making the tool's behavior fully comprehensible for an agent to select and invoke correctly.

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

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

The schema already covers all three parameters with 100% coverage, giving a baseline of 3. The description adds valuable semantics by explaining the two modes (topic vs explicit overrides), how the parameters relate to each other, and what the topic shortcuts represent. This enriches the meaning of the parameters beyond the schema descriptions.

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

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

The description opens with a specific verb and resource: it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It clearly distinguishes itself from sibling tools (e.g., polymarket_arbitrage) by focusing on cross-venue comparison and explicitly stating the two venues involved.

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: it explains two modes (topic shortcuts vs explicit ticker/slug) and how they interact. It also warns that pre-mapped topics often return compatibility_warning and that 'pre-mapped ≠ tradeable', giving a when-not-to-trust signal. However, it does not explicitly name alternative tools for different use cases.

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 and idempotent behavior. The description adds valuable context about scoping ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and the dual behavior of retrieving a single key versus listing all keys. This goes beyond annotation basics, though it could mention error handling for missing keys.

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 tight sentences, front-loaded with the core action. Every phrase earns its place: the retrieve/list distinction, usage guidance, scoping, and sibling references. No fluff or redundancy.

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

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

For a tool with a single optional parameter, no output schema, and clear annotations, this description is remarkably complete. It covers purpose, modes of operation, scoping, and how it relates to remember and forget. Nothing essential 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?

The schema already documents the 'key' parameter well (100% coverage). The description adds real meaning by giving concrete examples of key values (target ticker, address, prior research notes) and reinforcing the conceptual meaning of omitting the key. This enriches the schema's formal definition.

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: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It uses specific verbs and resources, and explicitly contrasts with sibling tools 'remember' and 'forget', making its purpose unmistakable.

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

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

It says 'Use to look up context the agent stored earlier — without re-deriving it from scratch', establishing when to use recall. It also explicitly guides pairing: 'Pair with remember to save, forget to delete', clarifying alternatives and exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description goes beyond by disclosing the mark_read side effect (flagging events read), the data fields returned, and the persisted feed location. It also clarifies the polling-friendly nature, adding valuable context not present 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?

The description is a single well-structured paragraph with the main action front-loaded. Every sentence provides useful information, from return payload to filtering, mark_read behavior, and the external endpoint. It is not overly long for a tool with five parameters, though the external URL could be considered extra.

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 appropriately explains the returned fields (source, citation_uri, raw payload). It covers filtering, mark_read semantics, and even provides an alternative access method. It does not mention unread_only in text, but the schema covers it, so the description is complete enough for this simple read 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 covers 100% of parameters, giving a baseline of 3. The description adds value by giving an example for type ("sec_8k"), specifying 'ISO timestamp' for since, and explaining the consequence of mark_read (next call shows only newer events). This elevates it 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: 'Pull fired events from your subscription feed.' It clearly states what is returned (most recent alerts with source, citation_uri, raw payload) and distinguishes itself from siblings like list_subscriptions by focusing on fired alerts rather than subscription management.

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: it is suitable for polling ('Polls work fine') and mentions an alternative REST endpoint for scripts/dashboards. However, it does not explicitly state when to prefer this over sibling tools like list_subscriptions or recent_changes, so it falls just 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 indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds value by detailing the parallel fan-out to SEC EDGAR, GDELT/GNews fallback logic, USPTO soft-fail due to API sunset, and the exact return structure (changes[], total_changes, citation URIs). This goes well beyond the annotations.

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

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

The description is dense but well-structured, starting with user-intent examples, then the core definition, fan-out details, and return format. While slightly long, every sentence contributes meaningful information. The structure aids comprehension despite the length.

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

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

The tool is complex with multiple sources, date handling, and fallback logic. The description covers all key aspects: sources, fallback behavior, date formats, return shape, and the alternative tool. Since there is no output schema, explaining the return structure is essential and is done clearly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical guidance for the `since` parameter (ISO date vs relative shorthand, recommended '30d'/'1m') and provides examples for `value` (ticker or CIK). This exceeds schema descriptions, though not exhaustively for all edge cases.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with specific verbs like 'fans out' and 'returns'. It distinguishes from the sibling entity_profile by targeting dynamic changes rather than a static profile. Example queries make the purpose immediately recognizable.

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

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

Explicitly states when to use this tool ('change feed for a company in the last N days/weeks/months') and when to use an alternative ('Use entity_profile instead when you want the static profile'). Also describes fallback behavior (GDELT→GNews) and soft-fail conditions, giving clear context for when results may be incomplete.

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

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

The description adds substantial behavioral context beyond the annotations: persistence across sessions, scoping by identifier, and the difference between authenticated (persistent) and anonymous (24-hour retention) sessions. These details are not present in the annotations, making the description highly 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 appropriately sized and front-loaded, starting with the core purpose and then expanding into usage and technical details. Every sentence adds value—examples, scoping, retention policy, and sibling references—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?

For a simple two-parameter tool with no output schema, the description is complete: it covers purpose, usage context, persistence behavior, authentication differences, and relationships with sibling tools. There are no significant gaps.

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

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

The input schema provides 100% coverage with descriptive examples for both parameters (key and value). The description adds no extra parameter-level details, but the schema already handles semantics adequately, so the baseline score 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 clearly states the tool saves data for later reuse, with a specific verb and resource ('Save data'). It provides concrete examples of what to store (e.g., resolved ticker, user preference) and distinguishes it from siblings by describing the key-value pair storage and pairing with recall/forget.

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

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

Explicitly defines when to use the tool ('Use when you discover something worth carrying forward') and mentions the benefit ('so you don't have to look it up again'). It also names sibling tools for related operations ('Pair with recall to retrieve later, forget to delete'), providing clear alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: internal endpoint cascading, auto-disambiguation, acceptance of multiple input formats, and specific return payloads including citation URIs. This is rich context well beyond the structured annotations.

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

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

The description is well-organized with leading user-phrase examples, a clear 'Use FIRST' directive, and a structured breakdown of supported types. It is a bit dense, but every sentence contributes value; nothing is wasted.

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 compensates by enumerating return fields and citation URIs for both entity types. It also explains input variations and positions the tool within the broader workflow ('other tools require as input'), making it complete for an agent.

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

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

Although schema coverage is 100%, the description goes far beyond it by detailing what each type returns (e.g., company returns ticker + 10-digit CIK + company_name from SEC EDGAR; drug returns RxCUI + ingredient + brand from RxNorm) and explains input variants. This adds significant meaning.

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

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

The description clearly identifies the tool as an entity resolver: 'resolve a user-spoken NAME to the canonical/official identifier' with concrete examples like ticker, CIK, and RxCUI. It also distinguishes itself from sibling tools by noting 'other tools require as input,' making its role unique.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and mentions it 'replaces 2-3 manual lookups,' giving clear context. It does not name specific alternatives or when-not-to-use conditions, but the guidance is strong enough.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive, lowering the bar for description transparency. The description adds valuable behavior beyond that: it says the tool 'Probes each entity ... with ai_visibility_check, ranks by score', and discloses the output fields ('ranked list with score, confidence, signal density per entity'). This is meaningful context that annotations alone don't provide.

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

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

The description is extremely concise: two sentences (plus a quoted example) accomplish everything. The action is front-loaded, and each sentence adds critical information—the probe method, ranking behavior, return format, and a concrete use case—without any fluff or repetition of schema details.

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

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

With no output schema, the description compensates by clearly stating the return format ('ranked list with score, confidence, signal density per entity'). It also explains the process (probes each entity with ai_visibility_check, ranks by score) and gives a realistic scenario. Minor gaps remain, such as how results are aggregated when multiple models are specified, but for a comparison tool of this complexity the description is sufficiently complete.

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

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

Schema description coverage is 100%—every parameter (entities, models, _apiKey, context) has a thorough description, including the nuance that the first entity is treated as the subject. The tool description adds no additional parameter semantics beyond what the schema already covers; it merely mentions 'your brand + N competitors', which is already implicit in the entities parameter description. Thus 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 opens with the specific action 'Compare AI visibility across multiple entities side-by-side', immediately distinguishing this from single-entity tools like ai_visibility_check. It further clarifies the scope by mentioning 'your brand + N competitors' and naming the exact probing mechanism (ai_visibility_check), making the tool's role completely unambiguous.

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

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

Explicitly frames the tool for 'competitive AI-marketing audits' with a concrete example question ('does Claude know about us as well as our competitors?'), giving clear guidance on when to use it. It implies that for a single entity one would use ai_visibility_check instead, but it doesn't explicitly state this exclusion or name other alternative tools, so it falls short of a full when-not-to-use specification.

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

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

The description adds substantial behavioral context beyond the annotations: it describes the fan-out to multiple sources, graceful degradation on partial failures, a potential 5-30s latency for bundlephobia's first measurement, and the sources_failed field. This is valuable information not present in the readOnly/hint 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 and front-loaded with the core purpose, followed by usage triggers, return details, scope, and failure behavior. Every sentence provides value, though the single long paragraph could be slightly more scannable with bullet points. The length is justified by the tool's complexity.

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

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

With no output schema, the description thoroughly enumerates the return contents (summary block fields, per-advisory details, links, alternative versions). It also covers ecosystem scope, timing, and failure degradation, making it complete for an agent to invoke and interpret results.

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

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

The input schema already provides comprehensive descriptions for both parameters (package and version), covering scoped packages and default behavior. The description does not add extra parameter-level semantics beyond what the schema states, so the baseline score of 3 for high schema coverage is appropriate.

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

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

The description clearly states the tool's purpose: a composite check to evaluate whether to add an npm package, aggregating data from deps.dev and bundlephobia. It lists the specific data points (license, advisories, version history, bundle size, dependency count, ESM/tree-shake support) and differentiates from direct deps.dev usage by scoping to NPM ecosystem in v1.

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 usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states when NOT to use it: for non-NPM ecosystems, directing to deps.dev:version directly. This clearly distinguishes the tool's appropriate context.

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

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

Goes beyond annotations by disclosing the embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, return contents (passages with offsets and scores), and the 200K char cap with truncation flag. No contradiction with readOnlyHint.

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 with clear front-loading of purpose. Each sentence earns its place, covering purpose, use case, sibling relation, and technical details 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?

For a read-only semantic search tool, the description fully covers what it does, when to use it, how it works, and key constraints. Annotations cover safety, so no gaps remain.

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

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

Schema already describes all parameters, but the description adds extra context: real-world examples for text (SEC 10-K, article), query examples, and 'top-N' framing for limit. This enhances understanding beyond the schema.

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

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

First sentence states 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by emphasizing searching within already-fetched text and explicitly pairs with ask_pipeworx_grounded.

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

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

Provides explicit when-to-use: 'Use when the record is too big to cram into the prompt.' It also names an alternative approach (ask_pipeworx_grounded) and explains how they complement each other.

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 auth requirements, delivery channel behavior (feed always on, email/SMS optional, SMS verification and 10/day cap), and webhook security details (HMAC-signed requests, secret returned once, auto-disable after 10 failures). This is extensive behavioral context that significantly aids an agent.

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 well-structured: purpose first, then requirements, supported types, and delivery channels. Every sentence adds substantive detail, with no filler or redundancy, earning its length for a tool with this complexity.

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

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

The description covers return value, auth, all main types with examples, delivery options with constraints, and webhook security. The two types not detailed in the description (patent_grant, clinical_trial) are described in the input schema, so the description is complete enough for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, and the description enriches this with concrete examples (e.g., 'items:["5.02"] = officer change' for sec_8k) and clarifies nested params and delivery semantics. It explains the meaning of enum values and gives practical usage patterns, making parameter selection intuitive.

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 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns the new subscription id, identifying the exact action and resource. This unambiguously distinguishes it from siblings like list_subscriptions and unsubscribe.

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

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

Provides concrete usage context: lists supported subscription types with examples, explains prerequisites (OAuth account required, anonymous/BYO cannot persist), and mentions how to retrieve alerts via recent_alerts. However, it does not explicitly name alternatives when not to use this tool, so it lacks explicit exclusions.

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

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

The description discloses behavioral traits beyond the read-only annotations: it returns category-bucketed example questions drawn from the live catalog, with each including exact tool and argument shape. It explains the no-argument vs. topic-focused behavior. Annotations already cover safety (readOnly, idempotent), so the description adds valuable context about output nature and scope.

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

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

The description is longer than average but front-loaded with natural language user queries that help with intent matching. Each section earns its place: examples, return value, parameter guidance, and usage instruction. It could be slightly tightened, but the structure is logical and readable.

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 only 1 optional parameter and no output schema, the description fully compensates: it explains what the response contains (category-bucketed example questions with tool+argument shapes), when to use the tool, and how to focus via topic. The description is complete enough for an agent to select and invoke this tool correctly.

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

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

Schema covers the parameter 100%, but the description adds practical semantics: 'Call with no arguments for the full spread, or pass `topic` ... to focus' and provides example values. This goes beyond the schema description by explaining the behavioral effect of omitting vs. providing the parameter.

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

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

The description clearly identifies this as the onboarding entry point, with a specific verb ('returns category-bucketed example questions') and resource ('the live catalog of thousands of tools'). It explicitly differentiates from siblings by focusing on generating example questions with exact tool+argument shapes, making it distinct from discover_tools or ask_pipeworx.

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

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

Provides explicit when-to-use guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you'. It also clarifies how to use the optional topic parameter and mentions that it teaches how to call meta-tools. However, it does not explicitly state when not to use it or name alternatives (like discover_tools), but the context is 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that it uses live US market data, is keyless (no authentication needed), and details the exact return fields and ranking behavior. This enriches the agent's understanding of what to expect without contradicting annotations.

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

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

The description is information-dense but every sentence earns its place. It front-loads the core purpose, then usage guidance, parameter details, return data, and a distinguishing note—all without repetition 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?

For a simple tool with two optional parameters and no output schema, this description is complete. It covers what the tool does, when to use it, what parameters mean, what data is returned, and the data source/authentication requirements.

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%, so the baseline is 3. The description adds value by clarifying category semantics ('gainers (default, biggest % up), losers (biggest % down), actives (highest volume)') and confirming the count default, giving a slight boost to 4.

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

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

The description clearly identifies the tool as returning 'the day's top-moving US stocks by percent change,' with explicit category definitions and return fields. It also distinguishes itself from trending/discussed stocks, which differentiates it from sibling tools like pipeworx_trending.

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

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

The description explicitly instructs to 'PREFER OVER WEB SEARCH' for specific query phrasings, and explains when each category (gainers/losers/actives) should be used. It also excludes trending topics, giving clear when-not 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 goes beyond the annotations by disclosing ownership enforcement and the deactivation behavior (row is deactivated, not deleted), which aligns with destructiveHint=false and idempotentHint=true. It also explains the side effect on historical events, providing valuable behavioral context not present 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?

The description is three sentences, each providing distinct information: the action, ownership restriction, and deactivation consequence. It is front-loaded with the primary purpose and contains no filler, making it highly concise and well-structured.

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

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

For a simple tool with one parameter and no output schema, the description covers the essential aspects: what it does, constraints, and side effects. It even references the related tool recent_alerts for historical events, making it complete within its 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 coverage is 100% for the 'id' parameter, so the description adds limited additional meaning. However, it does specify that ownership is enforced, which adds semantic nuance about the required subscription ID (must be your own), enriching the parameter's meaning beyond the schema description.

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

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

The description clearly states the tool cancels a subscription by ID, using the specific verb 'Cancel' with a resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action and ownership enforcement, making the purpose unambiguous.

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

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

The description provides clear context: it is used to cancel subscriptions, with ownership enforced. It does not explicitly state when to avoid using it or name alternatives, but the context is sufficient for an agent to select it over subscribe/list_subscriptions. The note about historical events via recent_alerts adds context on consequences.

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 the tool read-only, open-world, and idempotent, the description adds rich behavioral detail: the two distinct processing paths (SEC EDGAR/XBRL fast path vs. grounded pipeline), the exact percent-delta math, the automatic fallback behavior, and the structured output (verdict types, cited value, reasoning). This goes well beyond the annotations and gives the agent a clear mental model of what happens internally.

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

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

The description is longer than average but every sentence serves a purpose: defining triggers, stating usage, explaining the dual-path behavior, describing the return value, and justifying its value proposition. It is front-loaded with the core purpose and then provides necessary details. Slightly verbose but well-structured for a complex tool.

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

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

Given the tool's complexity, the description is exceptionally complete. It covers the input (natural language claim), the process (routing, evidence gathering, judgment), the output (verdict, value, citation, reasoning), and the rationale for using it (replaces multiple calls). There is no output schema, so the description's clear explanation of the return structure is essential and well-provided. No major gaps are apparent.

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

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

The input schema already covers both parameters with clear descriptions (claim and tolerance_pct). With 100% schema coverage, the baseline is 3. The description adds minimal parameter-specific detail (e.g., mentions tolerance in the context of 'exact percent-delta math' and hallucination detection), but it does not significantly enhance understanding beyond the schema. It is adequate but not exceptional.

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 claim verifier with explicit trigger phrases ('fact check', 'verify the claim that…'), and differentiates it from siblings by describing its role as a comprehensive, single-call claim verification tool. It also distinguishes between financial and non-financial claims, showing a specific and well-scoped purpose.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the automatic routing for different claim types and notes that it replaces 4–6 sequential calls, effectively guiding the agent to prefer this tool over chaining other tools. No explicit 'when not to use' is needed as the scope is clearly exhaustive.

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