deckofcards

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

Annotations already indicate safe read-only behavior, but the description adds context: default model, BYO key for Anthropic, per-model return structure, and combined view. It does not disclose rate limits or data usage, but is sufficient.

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

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

The description is four sentences, each serving a purpose: stating action, explaining defaults and costs, detailing output, and listing use cases. No redundant information.

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

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

Given no output schema, the description still explains return fields (score, confidence, signals, raw_response) and combined view. It covers input and use cases well, though could elaborate on 'signals'.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by explaining default model, API key usage, and disambiguation context, complementing 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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb and resource, and the uniqueness of the tool distinguishes it from siblings like scan_competitor_ai_presence.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies when to use but does not explicitly state when not to use or compare to alternatives, though the sibling list shows related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds context about routing, argument filling, and stable citation URIs. No contradictions, and useful behavioral traits beyond annotations.

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

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

Description is front-loaded with the key directive 'PREFER OVER WEB SEARCH'. It is somewhat lengthy with an extensive list of domains, but each part adds value. Could be slightly more concise, but it earns its space.

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 sufficiently explains return format (structured answer with citation URIs) and routing mechanism. It does not differentiate from all siblings, but the context is adequate for a general-purpose 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 has 6 parameters but all are aliases for the same question field, with schema coverage 100%. Description adds value by explaining the parameter accepts natural language queries and provides real examples, making it clear beyond the schema.

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

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

Description clearly states the tool routes questions to a vast set of tools and sources, returning structured answers with citations. It distinguishes from web search and lists many specific example use cases, making the purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides a rich list of when to use with examples. However, it does not explicitly differentiate from sibling tools like 'ask_pipeworx_grounded' or 'deep_research', leaving some ambiguity.

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

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

Annotations indicate read-only, open world, idempotent, non-destructive. The description adds critical behavioral traits: costs one extra LLM call, returns explicit refusal reasons ('not_in_source', 'no_tool_match', etc.), and explains the grounding process. No contradiction with annotations.

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

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

The description is well-structured, front-loaded with purpose, then behavior, use cases, return format, and refusal reasons. Every sentence adds value, and it is concise given the complexity.

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

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

Given the complexity (6 parameters, no output schema, many siblings), the description is highly complete. It covers purpose, routing, grounding, return format, refusal reasons, and when to use vs. alternatives. The only minor gap is detailed evidence format, but 'verbatim quote' suffices.

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 no extra meaning beyond the schema's parameter descriptions; it only notes that the question should be in natural language, which is already in the schema. No additional semantic guidance.

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 is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it routes like ask_pipeworx but extracts answers only from tool results. It distinguishes from ask_pipeworx by noting the extra LLM call and specific use cases for quoted/cited answers.

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: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also advises to 'prefer ask_pipeworx for casual lookups,' providing a clear alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details: fan-out patterns per category, response shapes, resolver contract, parent event extraction, news fallback handling, safety short-circuits, and resolution-rule risk. This provides deep transparency 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 comprehensive but very verbose, running multiple paragraphs with extensive examples and edge cases. While well-structured with clear sections, it could be more concise. It front-loads the main purpose but then goes into deep detail.

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

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

Given the tool's complexity (multiple input types, category-specific fan-outs, resolver logic, safety checks, and no output schema), the description is exceptionally complete. It covers every aspect: process, behavior, response structure, edge cases, and warnings.

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 parameter descriptions. The tool description adds value by explaining the types of 'market' input (slug, URL, question text) and elaborating on 'depth' and 'include_raw' effects (e.g., response size limits). This adds context beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types and output, and distinguishes this tool from siblings like polymarket_arbitrage which focus on different aspects.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not provide explicit when-not-to-use scenarios or alternatives, though it gives clear use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds specific behavioral details: for 'company' it pulls latest 10-K data and handles off-calendar fiscal years; for 'drug' it pulls FAERS counts, FDA approvals, and active trials. Also notes citation URIs in the response. 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?

Every sentence is information-dense with no fluff. The description front-loads example queries and the core action (comparison), then provides specifics per type. It earns its length by being exceptionally informative.

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

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

Given the tool's complexity (two entity types with different data sources), the description covers all necessary context: what data is retrieved, how results are sorted, and the output includes paired data and citation URIs. No output schema is needed because the description adequately sets expectations.

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 substantial meaning: explains what each 'type' pulls (revenue/net income/cash/debt for companies; adverse events/approvals/trials for drugs) and clarifies input format (tickers/CIKs vs drug names). It also describes output sorting, which is not in 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: side-by-side comparison of 2–5 companies or drugs. It provides specific example queries and distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance. It also explains sorting behavior for 'largest/most' queries, aiding correct invocation.

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

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

The description discloses key behaviors beyond annotations: returns a structured findings packet with verbatim evidence, confidence, source, fetched_at, citation, and explicit gaps. It notes that data is never invented. This aligns with annotations (readOnlyHint, idempotentHint) and provides critical context for a complex tool.

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

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

The description is somewhat lengthy but well-structured and front-loaded. It efficiently conveys all necessary information without redundancy. A minor improvement could be trimming redundant phrasing, but overall it earns its length.

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

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

Given the tool's complexity, no output schema, and the context of sibling tools, the description is remarkably complete. It explains the research process, output format, prerequisites, and expected execution time, leaving no major gaps for an AI agent to operate effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'thorough' depth requires a paid plan and that the 'question' parameter works well with broad/multi-part queries. This enhances understanding 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: 'Grounded multi-source research in ONE call' and explains that it decomposes questions, routes to tools, and extracts grounded answers. It distinguishes from sibling 'ask_pipeworx' by noting that tool is for single lookups, making the purpose specific and unambiguous.

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

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

Explicit guidance is provided: 'Use for broad or multi-part questions' and contrasts with 'ask_pipeworx' for single lookups. It also mentions requirements (Pipeworx account, paid plan for thorough) and expected latency (15-60s), helping the agent decide when to invoke this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed', which is useful 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?

The description is front-loaded with the core purpose ('Find tools by describing the data or task'), then provides detailed usage guidance, examples, and outcome. Every sentence contributes meaning, with no wasted words.

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

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

Given the tool's simplicity (search with one required parameter) and the absence of an output schema, the description fully covers what the tool does, when to use it, what it returns (schemas ready to call), and provides parameter aliases and examples.

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 that 'query' accepts natural language and lists aliases, and provides examples like 'analyze housing market trends'. This enhances understanding beyond the schema.

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

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

The description uses a specific verb ('Find') and resource ('tools'), and clearly states it is for browsing/searching/discovering tools. It distinguishes itself from sibling tools by being the discovery/search tool, while siblings are domain-specific 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 states 'Call this FIRST when you have many tools available and want to see the option set'. Also enumerates example tasks (SEC filings, FDA drugs, etc.) to clarify use cases.

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

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

Annotations indicate readOnlyHint=true and destructiveHint=false, but 'Draw cards' implies removing cards from deck, creating a contradiction. Description does not clarify whether the deck is modified, violating transparency.

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

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

Two concise sentences, no redundant information. Front-loaded with action and return, 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 output schema exists, description adequately mentions return values. However, fails to resolve the behavioral contradiction between annotations and typical card drawing semantics, leaving 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 description coverage is 100%, so description adds no additional meaning beyond schema. Baseline score of 3 applies as description merely echoes schema details.

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

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

Description clearly states 'Draw cards from a deck' with specific verb and resource, and distinguishes from sibling tools like new_deck and shuffle_deck by specifying action and return values.

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?

Usage is clear: draw cards from a deck, optionally multiple at once. However, lacks explicit when-not-to-use or mention of prerequisites like needing a deck created first, which is implied by deck_id parameter.

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 readOnlyHint, openWorldHint, idempotentHint, and non-destructive. Description adds behavioral details: fans out across multiple sources, USPTO PatentsView API sunset May 2025 (soft-fails), parallel execution, and specific return structure. 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?

Front-loaded with example queries and key directive. However, the description is somewhat lengthy, though each sentence provides unique value. Could be slightly more concise without losing information.

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

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

Despite no output schema, the description thoroughly explains return fields (CIK, filings with URIs, fundamentals sorted, patents, news fallback, LEI) and mentions limitations (up to 5 filings, soft-fail for patents). Adequate for a complex multi-source tool.

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

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

Schema coverage is 100% with both parameters described. Description adds meaning beyond schema: 'type' only supports 'company', 'value' accepts ticker or zero-padded CIK but not names, and references resolve_entity explicitly.

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 example user queries and clearly states 'full cross-source profile of a US public company in ONE parallel call.' It lists the specific sources and return fields, distinguishing it from sibling tools like resolve_entity (name not supported).

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack ... lookups when the user asks for a holistic view.' Also specifies when not to use (if only have name, use resolve_entity first), providing clear context and 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 destructiveHint=true and idempotentHint=true. Description confirms deletion but adds no new behavioral context beyond what the schema and annotations provide.

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

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

Three concise sentences: purpose, usage guidance, and related tools. No unnecessary words, front-loaded with key action.

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

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

With a single parameter, full schema coverage, and annotations providing behavioral hints, the description is complete for a simple delete operation.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. Description mentions 'by key' but adds no additional semantics or constraints beyond the schema.

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

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

Description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes itself 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?

Provides explicit when-to-use criteria: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions pairing with related tools but lacks explicit 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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds that the tool fetches the page, extracts content, and emits standard llms.txt markdown format. It does not contradict annotations and provides useful behavioral context.

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

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

The description is two sentences plus a bullet list, front-loaded with the main action and purpose. Every sentence adds value; no superfluous text.

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

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

Despite no output schema, the description explains the output format (text blob ready for site-root/llms.txt). It covers input, behavior, and use cases sufficiently for a simple 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 descriptions for both parameters. The description mentions max_links default and max but adds little beyond schema. Baseline 3 is appropriate; no significant enhancement.

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

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

The description uses a specific verb ('generate') and resource ('llms.txt file') and clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check' by focusing on generating a standard file format for AI crawlers.

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 use cases (client site indexing, personal project drafting, competitor auditing). However, it does not specify when not to use the tool or provide alternatives, but the context is clear enough for an AI agent to decide.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds that it returns specific fields and defaults to active only, which aligns 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?

Two sentences, front-loaded with purpose, 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?

No output schema but description lists returned fields. Simple tool, covers key aspects.

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%. Description adds value by explaining default behavior and the effect of include_inactive 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?

Description clearly states verb 'list' and resource 'active subscriptions', and lists returned fields (id, type, etc.). Distinguishes from siblings like subscribe/unsubscribe.

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

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

Explicitly tells when to use: review before adding more or to find an id to cancel. No mention of when not to use, but is clear enough.

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

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

The description says 'Create a shuffled deck', which implies a write operation that generates a new resource. However, annotations include readOnlyHint=true, indicating no side effects. This contradiction is serious and could mislead an AI agent. Without the contradiction, the description adequately mentions return values.

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

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

The description is two sentences long, front-loading the core purpose ('Create a shuffled deck') then quickly addressing the parameter. No unnecessary information; every sentence earns its place.

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

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

Given the presence of an output schema (not shown) and the tool's simplicity, the description provides essential information: what it does, what it returns, and how to use the parameter. It could hint at edge cases (e.g., max deck count) but is largely sufficient.

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

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

The input schema covers the single parameter 'count' thoroughly (100% coverage). The description adds an example ('2 for 104 cards') which clarifies usage but does not significantly add beyond the schema's description. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool creates a shuffled deck of playing cards, distinguishing it from siblings like 'shuffle_deck' (which shuffles existing decks) and 'draw_cards' (which draws from a deck). The verb 'create' and resource 'deck' are specific and unambiguous.

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

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

The description provides guidance on using the 'count' parameter to combine multiple decks (e.g., '2 for 104 cards'), but does not explicitly state when to use this tool versus alternatives like 'shuffle_deck' or 'draw_cards'. However, the context implies 'new_deck' is for creating new decks.

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 readOnlyHint=false and destructiveHint=false, but the description adds behavioral details beyond that: 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota.' It also mentions the team reads digests daily and signal affects roadmap, which are useful context. No contradiction with annotations.

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

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

The description is concise and front-loaded: the first sentence states the core purpose. Every sentence adds value (usage, constraints, output format). It is appropriately sized with no fluff.

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

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

Given 3 parameters, 2 required, full schema coverage, no output schema, and a unique sibling set, the description covers all necessary context: purpose, usage, behavioral traits, and parameter guidance. It is complete for an agent to use correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the enum meanings already in the schema for 'type' and does not add new meaning to the parameters. The 'context' parameter is implied by 'Describe the issue in terms of Pipeworx tools/packs' but not explained beyond schema. No added value, but no missing info.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb 'tell' and the resource 'Pipeworx team,' and lists categories (bug, feature, data_gap, praise). This tool is unique among siblings as none other handles feedback.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear what-not-to-do: 'don't paste the end-user's prompt.' This helps the agent decide between this and other 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?

Adds caching behavior, derivation source (CF analytics-engine), and no-PII guarantee beyond annotations (readOnly, idempotent, etc.). 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?

Concise paragraph with front-loaded main function, bulleted use cases, and no extraneous text. Every sentence earns its place.

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

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

Covers what returns, caching, use cases, and absence of PII. Lacks explicit output structure but acceptable for a one-parameter summary 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 already covers parameter with enum and description (100% coverage). Tool description adds context about shorter vs longer windows, enhancing meaning beyond schema.

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

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

Description clearly states verb ('returns'), resource ('top tools, top packs, total call volume'), and scope ('recent window 24h/7d/30d'). Differentiates from siblings like discover_tools by focusing on call volume trending.

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

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

Explicitly lists three use cases for when to use: discovering hot data, confirming canonical tools, aligning use case with demand. No explicit when-not-to-use, but context is clear.

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

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

Annotations already indicate readOnly, openWorld, idempotent. The description adds numerous behavioral details: failure on no args, Jaccard similarity threshold for cross-event pairs, partition filter dropping placeholders, and fill check using live CLOB depth. No contradictions with annotations.

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

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

The description is comprehensive and structured, starting with the requirement, then explaining modes, checks, response, and fill check. It is front-loaded and each sentence adds value, though slightly lengthy for maximum 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 complex tool with two modes, no output schema, and multiple behavioral aspects (partition check, fill check, semantic anchor), the description covers all necessary information: required parameters, mode selection, return fields, and error conditions. It also references a sibling tool for custom sizing.

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 substantial meaning: examples of slugs and seed questions, explanation of how each mode works (walking child markets vs scanning related events), and behavioral context like full URL acceptance. This goes well beyond the schema's one-liner descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing between single-event (event) and cross-event (topic) modes with specific examples. It differentiates 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 specifies that the tool requires one of event or topic, recommends event for specific markets and topic for cross-event scanning, and mentions that cross-event mode catches patterns missed by single-event. It also references polymarket_fill_risk for custom sizing, providing guidance on when to use 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?

The annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate a safe, read-only operation. The description adds extensive behavioral details: caching (1h KV keyed on knobs), response structure (by_segment, fed_candidates, _diagnostics), exclusion of Fed bets from ranking, and detailed behavior of each model family (e.g., 'placeholder-slug filter drops will-person-X...', 'partitions with >20% placeholder fraction skipped'). It also explains the edge calculation and the 24h-move warning. 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 very dense and technically detailed, covering many aspects in a single paragraph. While well-structured with parentheses and numbered lists, it is verbose for a tool description. Key information is front-loaded, but the length may hinder quick scanning. A more concise rewrite could improve usability without losing critical details.

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

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

Given the complexity (9 parameters, no output schema, multiple nested response segments), the description is exceptionally complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), the purpose of diagnostics (to explain empty segments), caching policy, and the behavior of each knob. Without an output schema, the description fully compensates by detailing what the tool returns and how the internal logic works.

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 9 parameters have individual descriptions in the input schema. The tool description provides additional context, such as clarifying that min_partition_leg_kelly applies to per-leg Kelly inside partitions, and grouping parameters like 'Tradeable-edge knobs' (min_liquidity, max_spread_pp). However, most parameter meanings are already clear from the schema, so the description adds marginal value beyond that. 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 explicitly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb ('scan... and return'), the resource ('Polymarket markets'), and the unique value proposition (disagreement with market price). The sibling tools include polymarket_arbitrage and polymarket_kalshi_spread, but this tool clearly focuses on model-driven and structural arbitrage edges, distinguishing it effectively.

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 positions the tool for the 'what should I bet on today' use case, indicating when to use it. It explains the three opportunity segments (model-driven, structural arbitrage, concentrated longshot) and provides edge-knobs for filtering. However, it lacks explicit guidance on when NOT to use this tool versus alternatives like polymarket_arbitrage, relying on implied differentiation through the detailed model description.

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 read-only, open world, idempotent, non-destructive. The description adds details about data sources (daily snapshots), behavior on cache-miss, and the bounded history depth, providing transparency 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 verbose but well-structured with clear sections (purpose, args, response fields, limits). It front-loads the purpose and provides comprehensive details. Could be slightly more concise, but the structure aids readability.

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

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

Without an output schema, the description fully compensates by detailing the response fields (tracked, expired, snapshot_dates) and their meanings. It also covers data sources, limitations, and parameter semantics, making it complete for a tool with 2 optional 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%, so baseline is 3. The description repeats parameter defaults and ranges but does not add significant new meaning beyond what the schema provides. It confirms the parameters' roles in lookback and window selection.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' that answers how long an edge has existed and if it's shrinking. This distinguishes it from sibling tools like polymarket_edges by focusing on time-series analysis and trend assessment.

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 for when to use the tool by explaining that a fresh edge differs from an old one, implying the tool helps assess edge quality. It also mentions limits (e.g., TTL, snapshot gaps), but does not explicitly specify 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 indicate readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds critical behavioral details: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage, and verdict, and explains basket behavior including forced directional risk. 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 dense and well-structured with capitalized headings (REQUIRES, SINGLE-MARKET, BASKET) and clear separation of modes. While slightly long (~150 words), every sentence adds necessary information, making it efficient overall.

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 enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) for both modes, explains verdicts, and warns about partial fills and forced directional risk. This fully compensates for the missing output schema.

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

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

Schema description coverage is 100%; all 4 parameters have descriptions. The tool description adds significant context: explains mode-specific behavior for side, market vs event, and clarifies size_usd interpretation (max spend/target proceeds for single-market, settlement notional for basket). This exceeds mere schema documentation.

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 checks realizable vs theoretical edge against live CLOB order-book depth, clearly distinguishes single-market and basket modes, and explains what each mode returns. It also specifies the context of use, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and provides rationale about thin books and partial fills. This gives clear when-to-use guidance and warns against misuse.

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 extensive behavioral details beyond annotations: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, and counters for dropped comparisons. It explains when spreads are mathematically meaningless. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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 well-structured: purpose, modes, response, safety fields, note. Every sentence adds value, though it could be slightly more concise. Still, it's front-loaded and readable.

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

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

Given the complexity (cross-venue, multiple parameters, compatibility warnings, temporal alignment), the description is comprehensive. It explains return values (no output schema), edge cases, and when results are meaningful. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the two modes ('topic' as pre-mapped shortcuts, explicit parameters override), gives examples, and describes the pre-mapped options. This enriches the schema definitions.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic and explicit parameters) and the response structure. This distinguishes it from sibling tools like polymarket_arbitrage (likely intra-venue) and polymarket_edges (single venue).

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

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

The description explains when to use: to compare same outcomes across venues. It warns that real spreads are rarer than macro shortcuts suggest and that most pre-mapped topics return compatibility warnings. It also explains when not to use (temporal mismatch, semantic mismatch). It lacks explicit alternative tool naming but provides good contextual guidance.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. Description adds value by stating scoping and listing behavior, without contradicting annotations.

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

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

Three sentences, front-loaded with core purpose, followed by examples and scope. No unnecessary words, each sentence earns its place.

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

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

Given low complexity, rich annotations, and complete schema, the description fully covers retrieval, listing, scope, and pairing with remember/forget. No output schema needed.

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

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

Schema covers the sole param 'key' with 100% coverage. Description adds context that omitting key lists all keys and gives an example, going beyond the schema's minimal description.

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

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

Description clearly states it retrieves saved values or lists all keys, using specific verbs ('retrieve', 'list'), and distinguishes from sibling tools 'remember' and 'forget' by referencing them directly.

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

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

Description explains when to use (look up context stored earlier, re-deriving without effort) and scoping (to identifier). It does not explicitly state when not to use, but this is straightforward for a read tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: the fields returned (source, citation_uri, raw payload) and the effect of mark_read:true (marks events read so subsequent calls exclude them). 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 a single paragraph of three sentences, each sentence providing distinct and necessary information without redundancy. 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?

Despite no output schema, the description adequately explains return values (source, citation_uri, payload) and the behavior of mark_read. It also provides an alternative access method, making the tool fully comprehensible.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds concrete examples (e.g., 'sec_8k' for type) and clarifies the semantics of mark_read and since, enhancing understanding beyond the schema.

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

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

The description clearly states the verb 'Pull fired events' and the resource 'from your subscription feed', distinguishing it from siblings like list_subscriptions which manage subscriptions rather than retrieving events.

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

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

Provides explicit guidance on filtering by type and since, and notes that polling works fine. Mentions an alternative REST endpoint for scripts/dashboards, but does not explicitly state when not to use this tool vs. alternatives.

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

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

Annotations already indicate readOnly, openWorld, and idempotent hints. The description adds significant behavioral context: multi-source fan-out, GDELT→GNews fallback, USPTO soft-fail due to API sunset, and return structure with citations, without contradicting annotations.

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

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

The description is front-loaded with example queries, efficiently covers all key aspects without redundancy, 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 the complexity of multi-source data with fallbacks and conditional behavior, the description covers most important aspects including return structure and soft-fail scenarios. However, it does not detail the structure of individual change items.

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 beyond schema: examples for since formats (ISO date and relative shorthand) and value formats (ticker or CIK), plus recommendation for typical monitoring window.

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 returns a change feed for a company from SEC, GDELT/GNews, and USPTO within a time window, and distinguishes from the sibling entity_profile tool by noting when to use each.

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 example queries showing when to use (e.g., 'What's new with X', 'latest on Y') and directs users to entity_profile for static profiles, clarifying the appropriate context.

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

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

Annotations indicate idempotent and non-destructive behavior; description adds scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions, enriching behavioral understanding without contradiction.

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

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

Two sentences with no wasted words. Front-loaded with purpose, then usage context, then behavioral details. Highly 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?

Covers purpose, when-to-use, behavioral traits, and pairing. Lacks mention of return value format, but tool has no output schema and the context is sufficient for correct invocation.

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

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

Schema coverage is 100% with good descriptions, but the tool description adds concrete examples (e.g., 'subject_property', 'target_ticker') that clarify usage beyond the schema. A minor deduction for not adding new structural detail.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples like tickers, addresses, and preferences. It implicitly distinguishes from siblings 'recall' and 'forget' by naming them as complementary 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 states when to use: when discovering something worth carrying forward. Mentions pairing with 'recall' and 'forget' for retrieval and deletion, providing clear guidance on 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, destructiveHint. The description adds that each call cascades through several lookup endpoints, replacing 2-3 manual lookups, and mentions auto-disambiguation for company. 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 moderately lengthy but well-structured: examples first, then usage guidance, then detailed per-type breakdown. It earns its sentences, though could be slightly streamlined.

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 adequately explains return formats for each entity type. It covers all required parameters and provides sufficient examples 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%, but the description adds meaning beyond schema by providing examples of valid inputs (ticker, CIK, name for company; brand/generic for drug) and explaining return types (e.g., ticker + CIK + company_name for company).

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 resolves user-spoken names to canonical identifiers, with specific examples like ticker, CIK, RxCUI. It distinguishes itself from sibling tools by its unique purpose.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID.' It provides clear context for when to use, but lacks explicit when-not-to-use or 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 mark the tool as read-only, idempotent, and non-destructive. The description adds context about probing each entity, ranking by score, and returning score, confidence, and signal density. No contradictions.

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

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

Three sentences, front-loaded with the core action, minimal waste. Every sentence adds value, including the concrete example and return fields.

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

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

For a tool with no output schema, the description specifies return fields (score, confidence, signal density) and explains internal probing. It provides sufficient context for an agent to understand the tool's purpose and output, though it could mention potential limitations like rate limiting or large entity counts.

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 description adds marginal value. It reiterates that entities are brand names and the first is the subject, but does not clarify further details like model behavior or API key usage 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 the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and returns a ranked list. It distinguishes itself from the sibling ai_visibility_check by specifying multiple entities and from compare_entities by focusing on AI presence.

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

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

The description gives explicit use cases like competitive AI-marketing audits and an example question. It implies when to use this over ai_visibility_check (single entity), but does not state exclusions or alternatives explicitly.

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 read-only, idempotent, non-destructive. Description adds that it fans out to external services, partial failures degrade gracefully, and bundlephobia's first measurement can take 5-30s. No contradiction.

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

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

Description is detailed but each sentence adds value. It starts with the core purpose and then lists returned fields and edge cases. Slightly long but well-structured.

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

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

No output schema, but description fully specifies the returned summary block fields, advisory details, links, and alternative versions. It also covers partial failures and timing, making the tool's behavior completely 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 3. The description adds that scoped packages (e.g., '@types/node') are accepted and version defaults to latest, which provides marginal extra 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 it is a composite check for npm packages, combining data from deps.dev and bundlephobia to answer questions about safety, popularity, and size. It specifies the verb 'scan' and resource 'dependency' and distinguishes from siblings by its unique functionality.

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 whenever an agent asks...' and provides context for NPM-only usage in v1, noting alternatives like direct deps.dev for other ecosystems. Also explains partial failure behavior and that bundlephobia may take extra time.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals technical details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and output includes offsets and similarity scores.

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 serves a purpose: core function, use case, pairing, technical details. Well-structured and not 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 3 parameters and no output schema, the description fully explains input requirements, output format (passages with offsets and scores), and limitations (200K char cap). Complements missing output schema.

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

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

Schema coverage is 100%, but description adds meaning: explains 'Pass the text you already pulled', gives example queries, and specifies limit range (1-20). This goes beyond the schema descriptions.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' and explains its purpose: to search within large text when it's too big for the prompt. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly advises 'Use when the record is too big to cram into the prompt' and provides alternative workflow with ask_pipeworx_grounded, giving clear context on when to use this tool vs. others.

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 indicates a write operation ('reshuffle and reset'), but the annotations declare readOnlyHint=true, which contradicts the description. No additional notes on auth, rate limits, or side effects are provided.

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

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

Two sentences, no filler, front-loaded with the key action. Every sentence is necessary and concise.

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

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

Given the tool's simplicity, annotations, and presence of an output schema, the description is complete. It mentions the return value (remaining card count) and the reset behavior, which are not fully covered by schema or annotations.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond what the schema already provides for the 'deck_id' parameter.

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

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

The description clearly states the action ('Reshuffle a deck') and the resource ('deck'). It also specifies that it resets drawn cards and returns the remaining count, which distinguishes it from sibling tools like 'draw_cards' and 'new_deck'.

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 want to shuffle and reset a deck) but does not explicitly state when to use it versus alternatives or provide exclusion criteria. No guidance on prerequisites or conditions.

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

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

Description discloses behavioral details beyond annotations: requires OAuth account, type-specific filters, delivery channel restrictions (SMS cap, webhook auto-disable, email templating), and verification steps. 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?

Information-dense prose with clear front-loading of purpose and id. Every sentence adds value, though slightly verbose. Could benefit from bullet points for readability, but structure is logical.

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 nested parameters, multiple types, and delivery channels, the description covers prerequisites, type details, delivery options, restrictions, and return value. No output schema but return value mentioned. Highly complete.

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

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

Adds substantial meaning beyond schema: explains enum values with examples and item codes, provides sample params for each type, and details delivery channel requirements (verification, signing, limits). Schema coverage 100%, but description enriches significantly.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It uses specific verbs and resources, distinguishing it from siblings like list_subscriptions and unsubscribe.

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

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

Provides clear context for when to use (proactive monitoring, requires OAuth account) and explains supported types and delivery channels. Lacks explicit when-not-to-use or direct alternatives among siblings, but context is sufficient.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. Description adds behavioral context: returns category-bucketed examples, call with no arguments for full spread, optional topic filtering. 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 well-structured: starts with common questions, states purpose, details output, then usage guidance. While slightly long, 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?

No output schema exists, but the description explains the return structure (category-bucketed examples with tool+argument shapes). Parameter is fully covered. Suitable for a simple onboarding 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 a single optional parameter (topic). Description adds semantic meaning by listing example topic values ('finance', 'pharma', etc.) and explaining the effect of omission versus inclusion.

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 an onboarding entry point that returns categorized example questions with exact tool calls. It uses specific verbs ('returns', 'call') and distinguishes from similar tools like ask_pipeworx and discover_tools.

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

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

Explicitly advises to use this tool first when unfamiliar with Pipeworx capabilities. Mentions optional topic parameter for focusing. Provides clear context but does not explicitly state when NOT to use it.

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

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

Annotations already indicate non-readonly and non-destructive behaviors. Description adds ownership enforcement and explains soft-delete (deactivate, not delete) which aligns with destructiveHint=false and provides useful context beyond annotations.

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

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

Two sentences, no fluff. Each sentence adds value: one states the action, the other clarifies ownership and behavior. Front-loaded with primary action.

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

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

Single-parameter tool with clear schema; description covers soft-delete and ownership. No output schema, but behavior is sufficiently explained for typical use. Sibling tools provide complementary context.

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

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

Schema coverage is 100% and the description for the 'id' parameter is clear. Description does not add any additional meaning beyond the schema, meeting 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?

Description clearly states the action ('Cancel a subscription by id') and identifies the specific resource ('subscription'). It distinguishes from sibling tools 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?

Provides clear context: ownership is enforced, so only own subscriptions can be canceled. Does not explicitly mention when not to use or list alternatives, but the constraint is well-stated.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details behavioral traits: returns a verdict with specific categories, extracted structured form, actual value with citation, and percent delta. It also notes it replaces 4-6 sequential calls, implying performance benefits. No contradictions with annotations.

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

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

The description is well-structured and concise. It front-loads with example trigger phrases, then states the purpose, domain, and outputs. Every sentence adds value without redundancy. The length is appropriate given the complexity of the tool.

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

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

Despite having no output schema, the description fully covers return values (verdict types, actual value with citation, delta). It specifies domain limitations and replacement of multiple calls, providing complete context for an agent to understand when and how to invoke the tool.

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

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

The single parameter 'claim' has a 100% schema description coverage with examples. The description adds domain context (company-financial claims) that is not in the schema, enhancing parameter understanding. Since schema already provides good coverage, the description adds moderate extra value, justifying a 4.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources for company-financial claims. It uses specific verbs like 'verify', 'check', and provides example triggers. The domain is explicitly scoped (US public companies, SEC EDGAR/XBRL), distinguishing it from generic search or research tools.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies the domain limitation (company-financial claims) but does not list alternative tools for other domains or explicitly state when not to use. The mention of replacing multiple sequential calls provides additional contextual guidance.

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