Cheapshark

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

Annotations confirm read-only, idempotent, non-destructive. Description adds: scoring details, per-model return structure, API key handling. No contradictions.

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

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

Four sentences, each adding essential information. Front-loaded with purpose, then parameter behavior, then use cases. No redundancy.

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

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

Covers purpose, parameters, return format (per-model fields + combined), and use cases. No output schema, so description adequately fills that gap.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: clarifies 'entity' with examples, explains models array defaults, and describes context disambiguation. Adds semantic value beyond schema.

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

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

Clearly states it 'probes LLMs' and 'scores visibility (0-100) per model'. Distinguishes from sibling tools like 'ask_pipeworx' and 'scan_competitor_ai_presence' by focusing on AI visibility scoring.

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

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

Explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Notes default model and condition for Anthropic (BYOK). No explicit when-to-avoid, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, and the description does not contradict these; instead, it reinforces a safe read-only tool for 'current or historical data'. The description adds useful behavioral context—such as 'one fast call', 'stable pipeworx:// citation URIs', and 'works on every tier'—which helps set expectations beyond the annotations. It slightly misses on detailing error handling or limits, but for a query tool this is quite thorough.

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

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

The description is long and information-dense, but every sentence earns its place: it leads with a strong directive ('PREFER OVER WEB SEARCH'), provides concrete examples, and explains when to step up to other tools. It could be trimmed slightly for readability, but the front-loaded structure and use of examples make it effective despite its length.

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

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

For a complex tool with many siblings, the description is remarkably complete: it covers use cases, provides concrete examples, explains routing behavior, and clarifies the distinction with alternatives. It even addresses potential user concerns (e.g., 'even if web search could also answer it') and specifies what makes this the default choice. Without an output schema, it still sets appropriate expectations about the response format (structured answer with citations).

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 6 parameters, but the description clarifies that 'question' is the primary parameter and the other five are simply aliases (q, text, input, query, prompt). This goes beyond the schema, which might otherwise mislead an agent into thinking there are 6 distinct parameters. The description effectively consolidates them into one logical input, which is valuable guidance not present in the schema alone.

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

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

The description explicitly states the tool 'routes the question to the right one of 5,566 tools across 1462 verified sources' and returns answers with citation URIs. It thoroughly details the types of queries it handles (SEC filings, FDA data, etc.) and distinguishes itself from siblings by naming specific alternatives (ask_pipeworx_grounded, deep_research). The purpose is unmistakable and well-scoped.

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 includes an explicit 'START HERE' directive, calls it the 'default entry point', and provides clear criteria for when to use alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'. It also gives example phrasings ('what is', 'look up', 'find') that signal when the tool is appropriate, going beyond generic advice.

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

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

Annotations already declare the tool as read-only, open-world, and idempotent. The description adds behavioral context beyond those hints: it is a full working router that 'falls back to nothing', that candidate routing improvements are only enabled while under test, and that results are compared against the stable router to decide merges. This helps an agent understand the experimental state and current behavior, though it does not discuss auth or rate limits.

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 dense sentences and is front-loaded with the essential beta-relationship in the first sentence. Every sentence adds useful context: current state, usage, and full functionality. It could be tightened by removing the parenthetical tool count, but it is appropriately organized and not needlessly verbose.

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

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

For a beta routing layer with a small one-parameter schema and no output schema, the description is complete enough. It explains the relationship to ask_pipeworx, the current candidate status, how to use it, and the fallback behavior. It does not describe return values, but it explicitly states the response shape is identical to ask_pipeworx, and the output schema is not present.

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

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

The input schema has 100% coverage; all six parameters are aliases for 'question' and are described in the schema. The description merely says 'same arguments' and does not add meaning beyond the schema. Given the full schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly identifies ask_pipeworx_beta as the beta version of ask_pipeworx, a universal router with the same 5,566 tools, arguments, and response shape. This distinguishes it from the stable ask_pipeworx sibling and conveys its role as an experimental edge. It could be slightly clearer that the tool answers natural-language questions by routing to other tools, but the title and question parameter make this obvious.

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 usage direction: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains the current state (no active candidate, so it matches ask_pipeworx exactly) and contrasts results with the stable router. It does not list exclusions like 'not for production' for the beta version, but the beta label itself conveys that 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 readOnlyHint/openWorldHint/idempotentHint=true, relaxing the burden, yet the description goes far beyond by disclosing the refusal contract (five enumerated refusal_reason values), the verbatim-quote evidence mechanism guaranteeing answer traceability, and the 'cannot invent facts' guarantee. The cost disclosure (one extra LLM call) is the kind of operational trait the rubric asks for. 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?

A dense ~150 words structured into a logical arc: what it is → how it works → success contract → refusal contract → when to use → cost tradeoff. Every sentence earns its place, and the structured return types (presented as JSON snippets) eliminate ambiguity without needing a full output schema. The logical flow (what → how → contract → policy) makes the length feel purposeful rather than verbose.

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

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

Given the tool's complexity (6 params, no output schema, single-question interface), the description is thorough: it covers the success response shape, enumeration of all refusal reasons, evidence source, and version-to-cost differences from its sibling. Minor gap: the evidence, confidence, and source fields' types aren't specified (e.g., is evidence a string or array?), but that may be intentionally left for the agent to discover. Overall, no critical information is missing.

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

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

Schema coverage is 100% — all six parameters are documented aliases (q, text, input, query, prompt) for 'question' with a clear natural-language description. Per rubric, high coverage warrants a baseline 3. The description adds contextual framing about what kinds of questions are appropriate (high-stakes, quotable facts) but doesn't add parameter-level syntax or format details beyond the schema, which is acceptable since none are needed.

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 value proposition—'Hallucination-resistant answer mode for high-stakes reads'—then explains the exact mechanism: route through 5,566 tools, fetch data, and extract an answer using ONLY what the result contains. It explicitly distinguishes this from its primary sibling ('Same routing as ask_pipeworx'... 'prefer ask_pipeworx for casual lookups'), satisfying the sibling-differentiation test.

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 an explicit when-to-use ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains (financial verdicts, legal claims, medical lookups, public statements). Equally explicit about when NOT to use it and why ('Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups'), naming the alternative directly.

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

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

The description extensively covers behavioral details: market resolution confidence, short-circuiting on low confidence, closed market handling, wide spread warnings, cancellation rule parsing, parent event extraction, and fallback mechanisms. This adds significant value beyond the annotations, which already indicate read-only, idempotent, and open-world behavior.

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

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

The description is relatively long but well-structured with sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, etc.) and front-loaded with the main purpose. Every section earns its place given the tool's complexity, though it could be trimmed slightly for conciseness.

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

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

Despite no output schema, the description covers all critical aspects: evidence packet, market comparison, edge analysis, resolver behavior, parent event info, news fields, safety mechanisms, and cancellation rules. It is comprehensive for a complex data-fetching tool.

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

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

Schema coverage is 100%, so the schema already documents all three parameters with descriptions. The tool description restates input types but does not add new parameter semantics beyond what the schema provides, meeting the baseline with no extra value.

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 researches Polymarket bets by pulling Pipeworx data. It specifies inputs and outputs, but does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, which may overlap in function.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It gives context for when to use the tool but lacks explicit 'when not to use' guidance or direct comparisons to sibling tools.

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

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

Beyond annotations (readOnlyHint=true, etc.), the description details key behaviors: it pulls latest 10-K data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, and returns sorted results with citation URIs. No contradiction with annotations.

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

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

The description is front-loaded with example queries and is well-structured. While it is a bit long, every sentence adds value. Minor redundancy could be trimmed, but overall it is efficient.

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

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

Despite no output schema, the description explains the return format: paired data + citation URIs and sorted by primary metric. Given the tool's complexity (two entity types, multiple data sources), the description provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%, but the description adds valuable context: for company type it lists specific financial metrics (revenue, net income, cash, debt) and for drug type it lists adverse events, FDA approvals, and trial counts. It also clarifies fiscal year handling, which goes 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 starts with explicit trigger phrases like 'Compare X and Y' and clearly states it performs side-by-side comparison of 2–5 entities. It distinguishes itself from siblings by emphasizing it replaces sequential lookups and providing specific data sources for each type.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear when-to-use guidance. It also explains what data each type retrieves, helping the agent choose the right tool and entity type.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, fully describing the tool's safety and idempotency. The description adds no additional behavioral context, failing to provide value beyond the structured fields.

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

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

At four words, the description is very concise but at the expense of informative content. It is front-loaded but too brief to fully convey purpose and usage. It earns its place, but could be expanded without losing conciseness.

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

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

For a simple retrieval tool with one parameter and annotations present, the description is minimally adequate. The existence of an output schema covers return values, but the description lacks details on scope or behavior, leaving 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?

With 0% schema description coverage, the description should compensate. It implies the 'id' parameter identifies which deal but gives no details on format, constraints, or examples. The single-line description adds minimal meaning beyond the schema.

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

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

The description 'Single deal detail' clearly identifies the tool's purpose: fetching details for one deal. It distinguishes from sibling tool 'deals' by specifying singular focus, but lacks specifics on what 'detail' includes.

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?

No usage guidance is provided. The description does not state when to use this tool versus alternatives like 'deals' (list) or other entity tools, nor does it mention prerequisites or 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=true, idempotentHint=true, and destructiveHint=false, so the safe-read nature is covered. The description adds meaningful context about the search scope, filters, and returned deal fields, but does not disclose potential rate limits, pagination behavior, or other edge-case traits.

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?

A single sentence that front-loads the core purpose and packs in filters and return fields with zero filler. Every phrase earns its place and the structure is immediately scannable.

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

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

The description, combined with annotations and an output schema, gives a solid foundation: filters, return fields, and safe/idempotent semantics are covered. It lacks explicit mention of sorting and pagination, but those are present in the schema/examples, so the overall package is nearly complete for a search tool.

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

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

Schema description coverage is only 20%, so the description must compensate. It adds semantics for several filters (store, price range, Metacritic score, Steam rating, title, sale status) but does not map these to exact parameter names or cover important parameters like sortBy, pageSize, pageNumber, exact, and steamAppID. Partial compensation for low schema coverage, but significant gaps remain.

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 action ('Search PC game deals') with a clear resource scope ('across digital stores') and enumerates filter dimensions and return fields. It clearly distinguishes itself from siblings like 'deal' (which likely retrieves a single deal) and 'stores' (which lists store IDs).

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

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

The description implies usage through its filter list but does not explicitly state when to use this tool versus alternatives such as 'deal', 'stores', or 'games'. No exclusions or alternative-recommendation are provided, leaving the agent to infer context from sibling names.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces the read-only nature with 'never invented' and gaps[] for unanswered facets. Beyond annotations, it discloses behavioral details: parallel decomposition across 5,566 tools, execution time (15-60s, thorough ~90s), hop fields, contradiction flags, gap recovery, semantic excerpting, and that citations are only present when fetchable. This is rich, non-contradictory context.

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

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

The description is long but earns its length given the tool's complexity. It front-loads the most critical caveat (account required, fallback) before the main content. Every section adds new information: what data sources, what not, alternatives, latency, output structure, and depth semantics. A small deduction for density — the paragraph is a wall of text with no list formatting, but it's well-organized and free of 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 complex tool with only 2 params, no output schema, and no nested objects, the description covers all essential aspects: prerequisites, auth, execution model, latency, return format, failure mode (gaps[]), contradiction behavior, and citation fetchability. It even handles edge cases like long-record excerpting and stable pipeworx:// citations. There is no significant missing information an agent would need 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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the practical impact of each depth level: quick=3 facets single hop, standard=3 with gap recovery + contradictions, thorough=6 with iterative lead-chasing. It also clarifies that the question parameter accepts broad/multi-part natural language. Only minor gap: doesn't give concrete depth value examples beyond counts, but that's already covered.

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: 'multi-source research across Pipeworx's 1462 STRUCTURED data sources' and distinguishes it from siblings by explicitly saying 'this is NOT open-web search' and contrasting with ask_pipeworx for single lookups. It also clearly identifies the output: a findings packet with verbatim evidence, confidence, source, fetched_at, and citations.

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 ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'). Names the alternative tool and explains why, plus gives examples of suitable questions. Also clarifies account requirements and when to fall back to ask_pipeworx if not signed in.

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 safe, idempotent read operation. Description adds that results include full input schemas with curated examples, ready to call directly, no second lookup needed. No contradiction.

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

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

Well-structured and front-loaded with purpose and examples. Slightly long due to detailed domain list, but each sentence adds value. Could be trimmed slightly without losing meaning.

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

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

Given no output schema, description explains return format (top-N tools with names, descriptions, schemas). Does not mention pagination or edge cases of limit, but limit parameter is documented in schema. Adequate for a discovery tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining aliases (query, q, task, search, description) and providing usage context for the query parameter, though it doesn't add new constraints.

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

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

Description clearly states it finds tools by describing data/task, lists many example domains (SEC filings, FDA drugs, etc.), and distinguishes from siblings like deep_research or search_within by focusing on tool 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?

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implicitly when not to use.

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

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

Annotations already declare readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint true. The description adds valuable behavioral context: it fans out across multiple sources, returns specific fields, notes patent source sunset (May 2025) with soft-fail behavior, and mentions news fallback (GDELT→GNews). No contradictions with annotations.

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

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

The description is a single dense paragraph that efficiently packs example triggers, usage instructions, data sources, and return fields. It is front-loaded with the core action and preferred use case. Every sentence adds value with minimal 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?

Despite no output schema, the description lists all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and specifies limits (up to 5 filings, LATEST 10-K fundamentals). It covers key sources and fallbacks, making the tool's behavior well-understood.

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 descriptive text for both parameters (type enum and value string). The description reinforces these constraints with examples (AAPL, 0000320193) and repeats the name-suggestion. While it adds some context, the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It specifies the verb (profile/research) and resource (US public company), and distinguishes from sibling tools by explicitly preferring it over chaining single-pack lookups.

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 usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity first if only a name is available, implying 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing stale or sensitive data, which is complementary. No contradictions.

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

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

Two sentences with no waste. First sentence states purpose, second gives usage scenarios. Front-loaded and efficient.

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

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

Given the single parameter and no output schema, the description fully covers purpose and usage. No missing information.

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

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

Schema has 100% coverage with a clear description for the sole parameter 'key'. The description adds no additional meaning beyond 'Memory key to delete'.

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

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

The description clearly states 'Delete a previously stored memory by key.' It uses a specific verb (Delete) and resource (memory), and distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also pairs with 'remember and recall' for context.

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

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

Annotations already declare the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds meaningful behavioral context by specifying the exact data returned: 'all active store deals, cheapest price ever, and Steam rating info', which goes 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 a single, concise sentence that front-loads the action ('Fetch') and efficiently conveys all necessary information. No extraneous words 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?

Given the presence of an output schema (mentioned in context signals), the description does not need to detail return values. It adequately covers the tool's functionality: fetching full deal details, price history, and Steam rating for a single game ID.

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

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

The input schema has 0% coverage in the description, but the description compensates by stating the parameter is a 'numeric game ID', clarifying its purpose. Though it doesn't explicitly define the format, it adds meaning beyond the raw schema type ('string') and example.

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

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

The description clearly states the action ('Fetch'), the resource ('full deal and price-history details for a single CheapShark game'), and the method ('by its numeric game ID'). It distinguishes itself from siblings like 'games' (which likely lists multiple) and 'deals' (which may focus on deals).

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 implicitly advises when to use the tool: when you have a specific game ID and need comprehensive details. It does not explicitly contrast with alternatives like 'games' or 'deal', but the context is clear enough for an agent to infer proper usage.

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

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

Annotations already declare readOnlyHint and idempotentHint, confirming safe read behavior. The description adds valuable detail about the return data: cheapest current deal, historical price, and active deal IDs. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that front-loads the core purpose. Every clause is essential, with no redundancy.

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

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

An output schema exists, so return structure detail is not needed. The description covers the essential aspects for a lookup tool. However, it does not explain the 'limit' parameter's effect on results, leaving a minor gap.

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

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

With 0% schema description coverage, the description partially compensates by mentioning lookup by 'title (or steamAppID)', but it does not explain 'exact' or 'limit' parameters. Some added value, but insufficient for full clarity.

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

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

The description clearly states the verb 'Look up', the specific resource 'PC game', and the catalog 'CheapShark'. It details the output: cheapest current deal, historical price, and active deal IDs. This distinguishes it from sibling tools like 'deals' which likely list multiple deals.

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

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

The description implies usage when you have a game title or Steam AppID, but it lacks explicit guidance on when to use this tool versus alternatives like 'deals' or 'deal'. No exclusions or prerequisites are mentioned.

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, not destructive. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' No contradiction.

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

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

Two sentences plus a short bullet list of use cases. Every sentence provides value, no fluff. Front-loaded with main purpose.

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

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

Given the richness of annotations and schema, the description adequately covers purpose, behavior, and usage. Minor gap: no mention of error handling or rate limits, but acceptable for a simple generation tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds context about the output format but does not elaborate on parameter behavior beyond schema defaults. Baseline 3 is appropriate.

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

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

The description clearly states it 'Generate a production-ready llms.txt file for any URL' and explains the purpose for AI crawlers. It specifies the action, resource, and output format, and implicitly distinguishes from siblings like 'ai_visibility_check'.

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: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds specific return fields and notes that 'active' is default. Could mention pagination or limits but overall good.

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

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

Two sentences, front-loaded with core action and return fields. Every sentence adds value, no redundancy.

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

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

Covers purpose, parameter, return format, and use cases despite no output schema. Could mention sorting or limits but minor gap.

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

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

Schema covers 100% of param description. The description does not add new info beyond what's in the schema. 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?

States specific verb 'List' and resource 'subscriptions', includes scope 'caller's active'. Clearly distinguishes from sibling tools like subscribe and unsubscribe which are mutation tools.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Implies when not to use (e.g., if just subscribing) and points to alternatives (subscribe, unsubscribe).

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 (all false), the description discloses rate limits ('Rate-limited to 5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and human review process ('digests daily and signal directly affects roadmap'). No annotation contradictions.

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

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

Every sentence carries information, but the entire description is one dense paragraph. It is front-loaded with the primary purpose and then covers exclusions, token flow, limits, and business context. While efficient, it could benefit from light structuring (e.g., bullet points for the claim_token process) without losing content. Still far better than typical tool descriptions.

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 feedback tool with unusual behaviors (anonymous token tracking, rate limits, exclusion of non-Pipeworx tools), the description leaves no gaps. It explains prerequisites (none), how to use the token, what happens with the feedback, and even gives a hint about tool naming. No output schema is needed; the description covers usage outcomes adequately.

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 good per-parameter descriptions, so baseline is 3. The description adds value above the schema by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which clarifies the parameter's interactive usage. It also reinforces the type enum meanings implicitly.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise), which distinguishes it clearly from all sibling tools. No other tool has this 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?

Provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data...'), and an explicit exclusion for tools from other MCP servers ('if the tool came from a different MCP server... file it with that server instead'). Also clarifies ambiguity with 'Not sure? Pipeworx tool names are the ones this connection lists.' This is exemplary 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 destructiveHint. The description adds value beyond these by noting the data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). No contradictions.

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

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

The description is two short paragraphs: first explains output, second gives use cases and technical details. Every sentence adds value, no redundancy, and essential information is front-loaded.

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

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

Given the tool is a simple read-only trending query with no output schema, the description fully covers what it does, why to use it, and how the parameter works. It is complete for agent understanding.

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

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

Schema covers 100% of the single parameter with enum and description. The description adds meaningful insight: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' which helps the agent interpret the parameter's effect.

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 returns 'top tools, top packs, and total call volume' over a window, using specific verb+resource ('what other AI agents are calling'). It distinguishes from siblings like 'discover_tools' by focusing on trending usage.

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

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

The description explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains when to use shorter vs longer windows. It lacks explicit exclusion of when not to use, but the guidance is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral context: explains the partition_check logic (sum of YES prices should ≈1, deviations >3pp signal), semantic anchor (Jaccard similarity ≥0.30), partition filter (drops placeholder slugs), and fill check against live CLOB depth (theoretical vs realizable edge). It even warns against trading when realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is lengthy but well-structured with line breaks separating logical sections (modes, semantic anchor, partition filter, response, fill check). It is front-loaded with the core purpose. Every sentence adds value, though some detail could be condensed without loss. Overall, it earns its length.

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

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

Despite lacking an output schema, the description thoroughly details the response structure: opportunities[] with gap_pp, suggested_trade, reasoning, monotonicity context; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade; and fill check results. It covers all inputs, logic, filtering, and edge cases. The tool is complex, and the description handles it completely.

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 both event and topic parameters described. The description enriches these by providing examples of valid inputs (e.g., 'fed-decision-may-2026') and explaining the behavior difference between event and topic modes. It also clarifies that full Polymarket URLs are accepted for the event 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 explicitly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It clearly distinguishes three modes: no-args (trending scan of top 200 markets), event (specific market slug with partition check), and topic (cross-event scan). This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides clear guidance on when to use each mode: no args for a general scan, event for a specific market (recommended), and topic for cross-event scanning. It also advises when not to trade (realizable_edge_pp <= 0) and suggests using polymarket_fill_risk for custom sizing. However, it does not explicitly compare against alternative sibling tools, though the guidance 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?

The description discloses extensive behavioral traits beyond the annotations, including detailed model family methodologies, caching (1h at KV level), exclusion of Fed bets from ranking, response structure with diagnostics, and edge calculation details (net of slippage). This adds significant value over the annotations, which only indicate read-only, idempotent, and non-destructive behavior.

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 (over 500 words) but well-structured, starting with the main purpose, then detailing model families, opportunity fields, knobs, and response format. Each sentence adds value, though it could be more concise for quicker agent comprehension. The front-loading of the purpose is excellent.

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, no output schema), the description is comprehensive. It explains the output structure (by_segment, fed_candidates, diagnostics), all response fields, model algorithms, and parameter usage. There are no significant gaps, making it complete for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly act as 'tradeable-edge filters' and how they interact with the model logic. This extra context justifies a score above baseline.

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

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

The description starts with a clear verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It explicitly states the tool's purpose and distinguishes it from siblings by focusing on Pipeworx data disagreement and being built for 'what should I bet on today' without paging hundreds of markets.

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, such as 'what should I bet on today' and mentions that Fed candidates are excluded from ranking. However, it does not explicitly compare with sibling tools like polymarket_arbitrage or bet_research, nor does it state when not to use it. The guidance is present but not exhaustive.

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

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

The description goes well beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing how snapshots work, trend computations (new, widening, stable, decaying), the meaning of decay_pp_per_day, and limitations like 60-day TTL and daily closes. No contradictions with annotations.

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

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

The description is front-loaded with the core purpose and provides a wealth of information in a single paragraph. It could be more structured with bullet points for clarity, but it is not verbose and every sentence adds value.

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

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

Given no output schema, the description fully explains the response structure (tracked[], expired[], snapshot_dates[]), including meanings of each field. It also covers the trend computation and limitations, making the tool's behavior fully 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?

The schema covers 100% of parameters. The description adds value by explaining the 'snapshot family' concept for window and clarifies the default and max for days, though it slightly overlaps with schema. The extra context about what each parameter controls in terms of snapshots enhances understanding.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes itself from sibling tools like polymarket_edges which provides raw edges, while this tool tracks their persistence over time.

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 context on when to use this tool by contrasting a fresh wide edge versus a 3-week-old wide edge, implying the need to assess edge persistence. It explains the output structure and limitations, but does not explicitly state when not to use it or name alternative tools.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. The description adds beyond: it returns verdicts (clean|degraded|cannot_fill), explains walking the ladder, and warns about forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is dense but well-structured with paragraphs and capital key terms. Every sentence adds value. Slightly verbose but justified given the complexity of the tool and the need to cover two modes thoroughly.

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

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

No output schema, so the description must detail return values. It does so comprehensively: for single-market (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket (theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk). Covers edge cases and risks.

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% (baseline 3). The description adds beyond schema: it explains that one of market or event is required, clarifies size_usd interpretation differs by mode (spend vs target proceeds vs settlement notional), and describes side defaults/auto behavior. Provides non-obvious semantics.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains the rationale (theoretical overround not capturable, partial fills create unhedged positions). It also describes the two modes and which parameters to use. Lacks explicit when-not, but 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?

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds substantial behavioral context: temporal_alignment, skipped_cross_type/subtype counters, compatibility_warning cases. It explains that real cross-venue spreads are rarer than the shortcut list suggests. No contradictions with annotations.

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

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

The description is relatively long (multiple paragraphs) but every sentence carries unique information. It is front-loaded with the core purpose and then systematically covers modes, response, and safety fields. A more concise version could exist, but given the complexity, the length is justified 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?

With 3 parameters, no required ones, and no output schema, the description covers everything: both modes, response structure (leg-by-leg prices, matched spread, top spreads), safety fields (compatibility_warning, temporal_alignment, skipped counters). It even explains edge cases like non-equivalent bet shapes. The agent can confidently select and invoke this tool.

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

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

Schema coverage is 100%, but the description adds significant meaning: lists all 10 topic shortcuts, explains that explicit parameters override the topic-mapped side. It clarifies the purpose of each parameter and provides examples. The description goes beyond the schema's brief descriptions.

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

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

The description clearly states it computes cross-venue spreads between Kalshi and Polymarket, explains two modes (topic shortcuts and explicit tickers), and distinguishes itself from sibling tools like polymarket_arbitrage. It uses specific verbs ('computes', 'fetches', 'exposes') and describes the output (spread in pp).

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: topic mode for common macro shortcuts, explicit mode for custom pairings. It warns that pre-mapped topics often return compatibility_warning and are not necessarily tradeable. It explains compatibility_warning conditions (non-equivalent bet shapes or semantically unrelated events) so agents know when the tool is appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context: that listing all keys is achieved by omitting the key argument, and that the tool is scoped to an identifier. It does not contradict annotations. Credit is given for adding context beyond the structured fields.

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

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

The description is three sentences long, front-loaded with the primary action. Each sentence serves a distinct purpose: (1) defines the operation, (2) provides usage examples, (3) adds scoping and pairing information. No unnecessary words.

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

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

For a tool with one optional parameter and no output schema, the description fully covers all necessary aspects: purpose, usage, scoping, and relationships with sibling tools. It is complete and leaves no 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?

Schema coverage is 100% (the 'key' parameter has a description). The description adds value by explaining that omitting the key lists all saved keys, which is a nuance not captured in the schema alone. This goes beyond what the schema 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 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. It specifies the verb (retrieve/list) and resource (saved keys/values), and distinguishes from siblings like 'remember' (save) and 'forget' (delete), as evidenced by the mention of pairing with them.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping ('Scoped to your identifier') and pairing with related tools. However, it does not explicitly state when not to use it or provide direct alternatives beyond remember and forget, which slightly reduces the score from 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 declare readOnlyHint=true, but the description transparently explains that setting mark_read:true flags events as read, modifying state. It also discloses the return format and alternative access method, adding context beyond annotations without contradiction.

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

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

The description is concise, with three sentences that front-load the purpose and key details. No redundant information; every part contributes to understanding the tool's functionality.

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?

Although no output schema is provided, the description clearly states what each returned alert contains (source, citation_uri, raw payload). It also explains the side-effect of mark_read and the alternative access method, 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the purpose of each parameter in a narrative, enhancing understanding beyond the schema descriptions (e.g., explaining mark_read effect on future calls).

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying the resource and action. It distinguishes itself from sibling tools like list_subscriptions and subscribe, which manage subscriptions rather than retrieve alerts.

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

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

The description mentions that polling works fine and provides an alternative API endpoint for scripts/dashboards, offering guidance on when to use the tool versus direct API access. However, it does not explicitly exclude usage in other contexts or compare with siblings.

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

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

The description adds behavioral context beyond annotations: it fans out to SEC EDGAR, GDELT→GNews fallback, and USPTO with a note about soft-failure. It also mentions return format and that it makes 'ONE parallel call'. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is moderately long but front-loaded with examples. Each sentence adds value, explaining sources, fallback, and parameter usage. It could be slightly more concise, but overall well-structured 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?

Despite no output schema, the description mentions return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers source behavior and fallback. Missing details like pagination or limits, but sufficient for a tool with 3 parameters.

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

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

Schema coverage is 100%, but the description adds helpful guidance: for `since` it explains relative shorthand like '30d' and suggests typical values; for `type` it notes only 'company' is supported; for `value` it gives ticker/CIK examples. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a change feed for a company over a time window, with examples like 'What's new with X'. It explicitly distinguishes from the sibling tool entity_profile by advising when to use that instead. The verb 'change feed' and resource 'company' are specific.

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

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

The description provides usage context with example queries and specifies the `since` parameter format. It explicitly tells when NOT to use this tool: 'Use entity_profile instead when you want the static profile...'. However, it does not mention other alternatives like deep_research.

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 key-value storage scoped by identifier, persistence differences for authenticated vs anonymous users, and 24-hour retention. Adds behavioral context beyond annotations without contradiction.

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

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

Three sentences, front-loaded with purpose, no wasted words. Efficiently conveys all essential information.

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

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

Comprehensive given no output schema: covers purpose, usage, parameters, scoping, persistence, and sibling tools. No gaps.

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

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

Schema has 100% coverage with parameter descriptions; description adds concrete examples of keys (e.g., subject_property, target_ticker) that provide additional semantic guidance beyond schema.

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

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

Clearly states 'Save data the agent will need to reuse later' with specific verb and resource. Distinguishes from siblings recall and forget.

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

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

Explicitly tells when to use: when discovering something worth carrying forward. Mentions pairing with recall and forget for complete workflow.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial behavioral context: explains internal cascading through multiple endpoints, graceful degradation if GLEIF/OpenFIGI unavailable, explicit listing of unresolved identifiers, and source-labeling of results. This goes well beyond annotations and is consistent with 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 long but every sentence carries functional weight. It is front-loaded with example queries, then structured by supported types with detailed but relevant sub-details. The density is justified by the tool's complexity, and no information is redundant or filler.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, no output schema), the description is remarkably complete. It covers inputs, outputs (identifier types and labels), failure behavior (unresolved list), resilience, and even cites a protocol URL for drug citations. An agent has all needed information to select and invoke the tool correctly.

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

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

While the schema already documents both parameters (100% coverage), the description significantly enriches their semantics. For 'value', it lists accepted formats (ticker, CIK, ISIN, name) and provides examples like 'ozempic' for drugs. It also clarifies how the 'type' parameter changes resolution behavior. This adds substantial meaning beyond the schema.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers. It includes specific example queries ('ticker for...', 'find the CIK for...') and explicitly positions it as the first step when a name needs an ID, distinguishing it from search tools.

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

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

Provides explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also details supported types (company/drug) and input formats, plus notes that it replaces multiple manual lookups, giving clear context for selection over 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 indicate readOnly, openWorld, idempotent, and non-destructive. Description adds behavioral details not in annotations: probes multiple entities, returns ranked list with score, confidence, signal density. Could mention that it calls external APIs (Anthropic) and potential rate limits.

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 well-structured sentences with front-loaded purpose. No unnecessary words; every sentence adds value.

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

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

Adequately explains return format (ranked list with score, confidence, signal density) despite no output schema. All four parameters are meaningfully described. Could mention pagination or limits on entity count.

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

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

Schema coverage is 100%, but description adds meaning: 'entities' first treated as subject, 'models' default workers-ai, optional anthropic with _apiKey, 'context' shared for disambiguation. Adds value beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks results, and surfaces insights. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Explicitly states use for competitive AI-marketing audits and describes the process of probing, ranking, and identifying most/least recognized entities. Implies not for single-entity checks (use ai_visibility_check), though not explicit when-not.

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

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

Annotations already provide read-only, idempotent, and non-destructive hints. The description adds important behavioral details about partial failures (bundlephobia latency) and graceful degradation, enhancing beyond annotations.

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

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

The description is somewhat lengthy but every sentence adds value and it is well-organized: purpose first, then usage, return format, ecosystem limits, and failure behavior. Some minor redundancy could be trimmed.

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

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

No output schema exists, so the description must cover return values. It does so comprehensively: lists the summary block fields, per-advisory details, links, and alternative versions. Also covers ecosystem limitations and partial failures.

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 extra meaning by explaining scoped packages are accepted and version defaults to latest, which aids correct usage.

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

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

The description clearly states it's a composite check for evaluating npm packages, specifying the verb-noun ('scan dependency') and listing the data sources (deps.dev, bundlephobia). It distinguishes itself from generic search tools by being a one-call summary.

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

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

Explicitly tells when to use (agent asks about safety/popularity/size) and when not (non-NPM ecosystems have alternative tools). Provides clear context for alternatives.

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

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

Discloses truncation at 200K chars with flagging, embedding model (BGE-base-en), chunking (500-char overlapping), and return format (character offsets, similarity scores). Annotations already indicate read-only and idempotent; description adds significant behavioral detail beyond annotations.

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

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

Paragraph is well-structured with clear sections (statement, use case, technical details) but slightly verbose. Every sentence adds value, yet could be tightened slightly without losing meaning.

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

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

No output schema, but description thoroughly explains return values (passages with offsets and scores), covers truncation edge case, and provides embedding/chunking details. Complete for a search tool with given complexity.

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

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

Schema coverage is 100%, but description adds meaningful context: explains 'text' as fetched document, 'query' as natural-language with examples, and implies 'limit' via 'top-N passages'. Each parameter is clarified beyond schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and use case for large records.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides guidance on pairing with ask_pipeworx_grounded. Offers clear context for when to invoke.

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. The description adds no additional behavioral traits, such as whether the list is static or dynamic, or if it requires authentication. It doesn't contradict annotations.

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

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

The description is very concise (three words), but it may be too sparse. It could include more context without adding verbosity, such as what 'supported stores' refers to.

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 partially completes the tool's context. However, it omits details about the nature of stores, potential filtering, or ordering. Adequate for a simple list but not rich.

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?

There are no parameters, so the input schema is fully covered. The description doesn't need to add parameter details; it correctly describes a parameterless call.

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 'List supported stores' uses a clear verb and resource, defining the tool's action. It distinguishes it from sibling tools like 'games' or 'deals', though it doesn't explicitly contrast them.

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

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

No guidance on when to use this tool versus alternatives. The description doesn't mention any conditions, prerequisites, or context where listing stores is appropriate.

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

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

Adds significant behavioral context beyond annotations: OAuth requirement, delivery channel constraints (SMS cap, webhook auto-disable), and subscription persistence limitations. Annotations already provide openness and idempotency hints, description complements well.

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

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

Well-structured with front-loaded purpose, but slightly verbose on webhook HMAC details; could be more concise without losing value.

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

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

Covers prerequisites, all parameter details, delivery options, constraints, and expected return value (subscription id), despite no output schema. Comprehensive for the tool's complexity.

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

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

Schema coverage is 100%, yet description adds deep semantic detail for each parameter, especially for type-specific params and delivery channel validation rules, surpassing 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?

Clearly states the verb 'Create' and resource 'proactive monitoring subscription', explicitly distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation of a subscription.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types and their parameters, but does not explicitly cover when not to use or contrast with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and not destructive. The description adds behavioral context: it returns category-bucketed example questions with exact tool+argument shapes drawn from a live catalog. No contradictions.

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

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

The description is detailed but efficiently structured: it starts with a clear purpose statement and proceeds to behavior, argument, and usage guidance. Could be slightly tighter, but every sentence adds value.

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

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

Given no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shapes). It covers the tool's role as an onboarding entry point, making it complete for a discovery-oriented 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?

Input schema covers the single optional parameter 'topic' with 100% description coverage. Description adds semantics by listing example focus areas (finance, pharma, etc.) and explaining the effect of omitting vs. providing the argument.

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's an onboarding entry point for asking what Pipeworx can do, returning category-bucketed example questions. It uses specific verbs like 'returns category-bucketed example questions' and distinguishes from sibling tools by advising 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to pass a topic argument to focus. No explicit exclusions, but clear context for usage.

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 behavior beyond annotations: row is deactivated not deleted, historical events via 'recent_alerts'. Also mentions ownership enforcement.

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

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

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

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

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

Covers key aspects (purpose, deactivation, ownership), but lacks mention of error conditions for invalid ownership or id.

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

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

Schema already fully documents parameter 'id' with 100% coverage; description doesn't add extra meaning beyond 'by id'.

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

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

Clear verb 'cancel' targeting 'subscription by id', distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

States when to use (cancel subscription) and ownership enforcement, but doesn't explicitly mention when not to use or compare to alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral nuance: the distinction between could_not_verify (check did not happen) and unsupported (we looked and cover no source), the verification_error structure, and the specific verdict enumeration. This goes far beyond the annotations and gives the agent critical operating knowledge.

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

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

Though the description is lengthy, every sentence carries operational value: examples, routing logic, return contract, and caller warnings. The structure leads with usage examples, then technical behavior, then explicit callers-best-practice. No filler 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?

Given the tool's complexity and the absence of an output schema, the description fully compensates: it enumerates all possible verdicts, explains the meaning of edge case verdicts (could_not_verify vs unsupported), specifies the citation mechanism, and describes the fallback pipeline. This is complete enough for an agent to invoke and interpret results correctly without additional lookups.

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

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

Schema coverage is 100%, but the description adds extra meaning beyond the schema: it explains that tolerance_pct overrides the tolerance implied by the claim wording, and gives concrete guidance (set 1–2 for hallucination detection) and default behavior (capped at 5). The claim parameter is illustrated with real examples sharing the tool's phrasing conventions.

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

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

The description opens with a clear, specific purpose: natural-language claim verification against authoritative sources. It includes example phrasings ('Is it true that…', 'fact check', 'verify the claim that…'), distinguishes itself from broader research tools by scoping to factual correctness checking, and explicitly states it replaces 4–6 sequential calls.

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 tells the agent when to use it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further clarifies the routing logic (company-financial claims via SEC EDGAR path, any other factual claim via grounded pipeline), which helps the agent decide between this tool and alternatives. It also warns about could_not_verify not being evidence, preventing misuse.

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