Ygoprodeck

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that probing Anthropic requires a BYO API key and noting the default model. It does not contradict annotations.

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

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

Three sentences, front-loaded with the core action and output, no wasted words. Every sentence serves a purpose.

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

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

Given 4 parameters, no output schema, and good annotations, the description fully covers purpose, parameters, use cases, and output format. It is complete and self-contained.

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

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

Schema description coverage is 100%, but the description adds meaningful context beyond the schema: it mentions the default model (Workers AI Llama-3.3-70b free), explains that _apiKey is for Anthropic and passed straight through, and clarifies that context helps disambiguate common names.

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

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

The description clearly specifies the tool's action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and distinguishes this tool from its many siblings by focusing on AI visibility scoring.

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

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

The description states it is 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' providing clear context for when to use it. However, it does not explicitly mention when not to use it or compare to alternative tools.

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

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

Annotations already declare safe, idempotent read-only nature. Description adds that it returns citations with stable pipeworx:// URIs and works on every tier, providing additional useful 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?

Well-structured with key guidance front-loaded, examples provided, and escalation rules at end. Slightly wordy but all sentences earn their place.

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

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

For a tool routing to many sources, the description covers scope, alternatives, examples, and usage boundaries comprehensively despite having no 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 covers all parameters, and description adds that the tool fills arguments automatically and accepts multiple aliases for the question parameter, going beyond baseline.

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

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

The description clearly states it answers factual questions by routing to 4,482 tools across 1,129 sources, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says to prefer this over web search for factual questions, provides examples, and tells when to step up to grounded or deep research 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, idempotentHint, etc. The description adds rich behavioral details: same routing as ask_pipeworx, selects tool from 4,482, fills arguments, extracts answer only from result, returns refusal reasons. 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 a single paragraph that front-loads purpose, then details process, usage, and cost. It is somewhat lengthy but each sentence adds value. Could be slightly more concise 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 the description elaborately explains the success and refusal return formats (answer, evidence, confidence, source, etc.) and possible refusal reasons. It also covers routing, cost, and when to use, making it very complete.

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

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

Schema coverage is 100% with alias descriptions. The description adds 'Your question in natural language' but largely repeats alias info. Thus baseline 3 applies; the description provides minimal added meaning.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from the sibling 'ask_pipeworx' by explaining that it extracts answers only from tool results and returns evidence. The verb 'answer' and resource 'Pipeworx grounded' are specific.

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

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

Explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on... Prefer ask_pipeworx for casual lookups.' This tells when to use and when not to, and names the alternative sibling tool.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description details fan-out behavior, response shapes, resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits, closed market handling, wide-spread warnings, and resolution-rule risk. This is comprehensive and adds significant value.

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 thorough but verbose, spanning multiple paragraphs. It is front-loaded with the core purpose but could be more concise. Some details are essential, but structure could be improved.

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 (classifiers, fan-outs, safety behaviors, response shapes), the description is remarkably complete. It covers edge cases, resolution risks, and market states. No output schema, but explanation of response fields 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% for 3 parameters. Description adds value: market parameter gets examples, depth explains quick vs. thorough with default, include_raw explains when to use true. It provides nuance 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 it researches a Polymarket bet by pulling Pipeworx data, specifying input types (slug, URL, question text) and output (evidence packet + comparison). It effectively distinguishes itself from sibling tools like polymarket_arbitrage or polymarket_edges by focusing on data fan-out and research.

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

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

Provides explicit use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Classifiers and fan-out examples give context. Does not explicitly state when not to use, but the context is clear enough.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details data sources per type (SEC 10-K for companies, FAERS/FDA/trials for drugs), off-calendar fiscal year handling, sorting by primary metric, and output (paired data + citation URIs). No contradiction with annotations.

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

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

Front-loaded with common query patterns and imperative advice. Every sentence adds unique value—examples, data details, performance note. No redundant or filler 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?

Given the complexity (two entity types, multiple data sources) and no output schema, the description covers purpose, parameters, behavior, and usage. Minor omission: no mention of error handling for missing entities or invalid inputs, but annotations suggest open-world tolerance.

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

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

While schema coverage is 100%, the description enriches parameter meaning: explains what data each 'type' pulls (revenue, net income for company; adverse-event counts for drug) and gives concrete examples for 'values' (tickers, drug names). This helps the agent understand the return context.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It distinguishes from siblings like entity_profile and search tools by emphasizing that this replaces sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example queries and notes it replaces 8–15 sequential lookups, giving clear when-to-use guidance.

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

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

The description adds rich behavioral context beyond the annotations: account requirement (free with paid plan for thorough), return format ('findings packet: verbatim evidence + confidence + source + fetched_at + stable pipeworx:// citation per finding, with explicit gaps[]'), timing ('Expect 15-60s'), and the decomposition/parallel routing behavior. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description is fully consistent.

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

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

The description is long but well-structured, with the most critical information (account requirement and alternative) front-loaded. Every sentence serves a purpose, providing usage guidelines, behavioral details, and parameter semantics. It could be slightly more concise, but the density of useful information justifies the length.

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

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

Given the tool's complexity (2 parameters, 1 required, no nested objects, no output schema), the description is comprehensive. It explains the return format in detail, including fields like evidence, confidence, source, citation, and gaps[]. It also covers timing, account tiers, and when the tool returns empty results. The description compensates fully for the lack of an 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?

Both parameters (question, depth) are fully described in the schema (100% coverage). The description adds significant meaning beyond the schema: it explains the depth enum values ('quick=3, standard=5 (default), thorough=8 (paid plans)') and clarifies that the question can be 'broad/multi-part'. This extra context helps the agent choose appropriate values.

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

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

The description clearly defines the tool as a 'grounded multi-source research' tool that decomposes questions into facets and routes to tools in parallel. It distinguishes itself from siblings like ask_pipeworx (single lookup) and provides specific use cases (e.g., 'compare X and Y's regulatory + financial exposure'). The verb 'research' combined with the resource (structured data sources) and scope (broad/multi-part) makes the purpose unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions over structured data' and for breaking news or colloquial current-news topics, 'prefer ask_pipeworx'. It also mentions an alternative tool (ask_pipeworx) for single lookups, and notes the account requirement with a link to sign up, plus the paid plan for 'thorough' depth.

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, idempotent, non-destructive. Description adds beyond that: explains return format (names, descriptions, full input schemas with examples) and that results are callable without second lookup, providing valuable 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?

Well-structured: front-loaded purpose, then domains, then return value and usage. Slightly verbose but every sentence adds value, no redundancy.

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

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

Despite no output schema, description fully explains return content (tool names, descriptions, schemas with examples) and when to use. Complete for a discovery tool with no nested objects.

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

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

Schema coverage is 100%, so baseline is 3. Description mentions query accepting aliases and natural language, but this repeats schema info without adding new meaning.

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

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

Clearly states it finds tools by describing data or task, with specific domain examples like SEC filings, financials, FDA drugs, etc. Distinct from sibling tools which are specific actions (e.g., bet_research, entity_profile).

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set.' Provides clear context and when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: the data sources (SEC, XBRL, USPTO, GDELT, GLEIF), specific return fields, and a caveat about USPTO PatentsView API sunset. 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 packed with examples and details, but slightly verbose. It could be tightened while retaining all key information. However, it front-loads the purpose with example queries, which is effective.

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

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

Given the tool's complexity (multi-source aggregation, no output schema), the description fully covers purpose, when to use, parameters, and return structure (filings, fundamentals, patents, news, LEI). No gaps.

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

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

Schema coverage is 100% with descriptions for both 'type' and 'value'. The description reinforces that 'type' only supports 'company' and explains 'value' accepts ticker or zero-padded CIK, adding clarity 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 concrete examples ('Tell me about X', 'research Acme') and explicitly states it returns a 'full cross-source profile of a US public company in ONE parallel call'. It distinguishes itself from the sibling tool 'resolve_entity' by noting that names require that tool first.

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

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

It explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and provides clear when-not-to-use guidance: 'names not supported (use resolve_entity first if you only have a name)'.

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 destructive nature, but description adds valuable context about clearing sensitive data and stale context, enhancing transparency beyond structured fields.

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

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

Two concise sentences, front-loaded with purpose, no unnecessary words. Every sentence earns its place.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose and usage adequately. Could mention error handling but is sufficient given 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 coverage is 100% with a clear parameter description; the tool description does not add additional meaning or examples 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 'Delete' and the resource 'memory by key', distinguishing it from siblings 'remember' and 'recall'.

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

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

Explicitly provides three scenarios for use (stale context, task done, clear sensitive data) and mentions pairing with siblings, guiding appropriate 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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds behavioral details (fetching page, extracting title/description/links, emitting markdown format) and explains output usage, enhancing transparency without contradiction.

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

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

The description is concise with three sentences and a bullet list, front-loaded with purpose. Every sentence adds value, no redundancy.

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

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

For a simple tool with rich annotations and no output schema, the description covers return format (text blob), usage context, and steps. It lacks error handling or limitations but is sufficient for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it mentions max links default/max but the schema already describes parameters adequately.

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

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

The description clearly states the tool generates an llms.txt file for a URL, specifying the verb 'Generate' and the resource. It provides context about AI crawlers and mentions use cases, but does not explicitly differentiate from sibling tools 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 includes explicit use cases (client sites, personal projects, competitor auditing), but lacks guidance on when not to use this tool or alternatives. The context is clear but exclusions are absent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, providing a strong safety profile. The description adds value by detailing the returned data (ATK/DEF, prices, sets, etc.), offering additional behavioral context beyond annotations.

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

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

The description is concise with two sentences, front-loading the core function. Every word adds value, with no superfluous information.

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

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

For a simple tool with one parameter and no output schema, the description covers the tool's purpose and return values thoroughly. It could mention error cases or exact match behavior, but it is sufficiently complete.

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

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

Schema coverage is 100% with a clear description for the single 'name' parameter. The description does not add further semantics beyond what the schema provides, so a 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 looks up a single Yu-Gi-Oh! card by exact name and lists what it returns. It distinguishes itself from sibling tools like search_cards and random_card by focusing on a single card lookup with exact name.

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

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

The description implies when to use the tool (when you know the exact card name and want full details), but does not explicitly state when not to use it or mention alternatives. It is clear enough for proper usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by listing exact return fields and confirming it returns active subscriptions, 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?

Two sentences: first sentence states purpose and return fields, second sentence provides usage context. Front-loaded, no unnecessary words.

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

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

No output schema, but description explicitly returns id, type, params, created_at, last_fired_at, fire_count. Lacks details on pagination or ordering, but for a simple list tool this is sufficient.

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

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

Schema coverage is 100% with one parameter 'include_inactive' described. The description implies that by default inactive subscriptions are excluded ('active subscriptions'), but does not directly reference the parameter. Adequate but minimal added value.

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

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

Description clearly states 'List the caller's active subscriptions' and specifies the return fields (id, type, params, created_at, last_fired_at, fire_count). It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing only.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear use cases, though it does not explicitly mention when to avoid using it in favor of sibling tools.

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

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

The description adds significant behavioral context beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and team reads digests daily affecting roadmap. Annotations only indicate non-read-only and non-destructive, but description gives specific operational details.

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

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

The description is compact (4 sentences) but packed with information. It front-loads the purpose, then provides usage guidance, constraints, and value proposition. Every sentence serves a purpose with no redundancy.

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

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

The description covers all necessary aspects: what to send, how to structure, when to use each type, limitations (rate limit, quota), and impact (roadmap influence). No output schema is needed for this simple feedback tool, so completeness is high.

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

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

Despite 100% schema coverage, the description adds meaning by elaborating on the 'type' enum values (e.g., 'bug = something broke or returned wrong data'), explaining the 'context' object's role, and giving guidance on message content ('Be specific... 1-2 sentences typical'). This goes well 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: sending feedback (bugs, features, data_gaps, praise) to the Pipeworx team. It distinguishes from sibling tools which are all unrelated to feedback submission.

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

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

Explicit use cases are given: '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 provides a clear negative instruction: 'don't paste the end-user's prompt.' Additionally, it mentions rate limits and quota impact.

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, idempotent, non-destructive. The description adds value by revealing data source (CF analytics-engine), no PII, and caching range (5min-1h), which are not in annotations.

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

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

The description is efficient, with three bullet-like use cases and two supplementary sentences. It's front-loaded and every part contributes. Minor improvement could be more concise, but it's 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?

Given the simple tool with one optional parameter and no output schema, the description sufficiently explains what is returned (top tools, top packs, total call volume) and the caching behavior. It is complete 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 covers the parameter fully with enum and description. The description adds meaning by explaining the behavior of different windows: 'shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

The description clearly states it returns trending tools and packs with call volume, using specific verb 'Returns'. It distinguishes itself from siblings like ask_pipeworx or discover_tools by focusing on aggregate trend data.

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 three explicit use cases for when to use this tool, such as discovering hot data sources or confirming canonical choices. It lacks explicit when-not-to-use or direct comparisons to siblings, but the context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral detail: partition checks, fill checks, semantic anchor for similarity, partition filter, and handling of thin legs. It explains what happens if realizable_edge is non-positive.

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

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

The description is dense but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and bolded key terms. It could be slightly shorter, 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?

Given no output schema, the description explains response fields (opportunities, partition_check) and includes edge cases (fill check, placeholder filtering). It covers complex behavior and distinguishes from siblings like polymarket_edges and polymarket_fill_risk.

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% (both parameters described). The description adds significant meaning: event accepts slugs or full URLs, topic is a seed question, and explains mode behavior and constraints like Jaccard similarity.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific behavior for each, 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?

Explicit guidance on when to use event vs topic mode, including a recommendation for specific event mode. It warns that calling with no arguments fails and references sibling tool polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral traits beyond annotations: caching (1h KV-level keyed on knobs), slippage assumptions, filtering logic, diagnostics for empty segments, Fed bet exclusion rationale, and detailed calculation methods. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds deep transparency without contradiction.

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

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

The description is a single dense paragraph that front-loads purpose but buries important details like caching and diagnostics. While every sentence is informative, the lack of structure (e.g., bullet points or sections) makes it less scannable for an agent. It is complete but not optimally 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 9 parameters and no output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, fed_note, _diagnostics) and individual opportunity fields. It also covers caching, filtering logic, and edge cases like empty segments. This provides a complete mental model for the agent to invoke and interpret results 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?

With 100% schema description coverage, the baseline is 3, but the tool description adds substantial meaning to every parameter: it explains defaults, use cases, and adjustment guidance (e.g., slippage_pp explains Polymarket fee structure and when to adjust; min_partition_leg_kelly explains why min_kelly doesn't apply to partitions). This far exceeds basic 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 clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for daily betting discovery. It distinguishes itself from siblings like polymarket_arbitrage and bet_research by focusing on Pipeworx models and returning structured opportunities with edge metrics.

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 ("Built for 'what should I bet on today'") and explains the segments and tradeable-edge knobs. However, it lacks explicit when-not-to-use guidance or direct comparison to alternative tools like polymarket_arbitrage, though the purpose is clear enough for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds substantial behavioral context: snapshots written on cache-miss, gaps meaning no scan that day, 60-day TTL, decay from daily closes not intraday. 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?

The description is fairly long but well-structured: purpose, then response fields, then limitations. Each sentence contributes meaningful information. Minor redundancy could be trimmed, but overall 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?

No output schema exists, so the description fully compensates by detailing the response structure (tracked[], expired[], snapshot_dates[]) and limitations (TTL, start date). For a read-only data tool, this is comprehensive.

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

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

Schema coverage is 100% (both parameters documented). The description adds value by specifying defaults (days=14, window='1wk'), clamping (days clamp 2-30), and window family options (24hr, 1wk, 1mo) beyond the schema.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This is a specific verb+resource combination that distinguishes it from siblings like 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 implicitly guides usage by contrasting fresh wide edges with old wide edges, indicating when to use this tool (when time-based history matters). It doesn't explicitly state alternatives, but the sibling context provides differentiation.

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, openWorldHint, and non-destructive. The description significantly adds: requirement of market or event, details on return fields (top_of_book, vwap_fill_price, etc.), the danger of partial basket fills converting arb into unhedged directional position, and defaults/clamps. 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 relatively long but front-loaded with the purpose. Every sentence contributes value given the tool's complexity (two modes, edge cases, warnings). Could be slightly more concise, but the structure effectively conveys necessary 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 the tool's complexity and lack of output schema, the description comprehensively covers return values for both modes (single-market: top_of_book, vwap_fill_price, etc.; basket: theoretical_sum, realizable_sum, etc.), edge cases (thin books, partial fills), and the risk of unhedged directional positions. No missing contextual elements.

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, baseline 3. The description adds extra meaning: default behavior for side in basket mode (auto based on partition sum), interpretation of size_usd in basket mode (settlement notional), and clamp range. This adds value beyond the schema.

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

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

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

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the two modes (market vs event) and why it's necessary (theoretical overround not capturable, partial fills cause directional risk).

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds significant context: compatibility warnings for non-equivalent bet shapes, temporal alignment checks, skipped counters. No contradiction with annotations.

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

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

Description is well-structured with sections for modes, response, safety fields. Each sentence adds value. Slightly verbose but justified by complexity. Front-loaded with key modes.

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 with 100% schema coverage and no output schema, the description fully explains response shape, safety fields, and edge cases. An AI agent has enough context to use the tool correctly.

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

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

Schema covers all 3 parameters with descriptions. Description adds value by explaining the relationship between parameters (overrides, interaction of topic vs explicit) and providing examples. Could mention default behavior when no parameters given.

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 computes cross-venue spread between Kalshi and Polymarket. It distinguishes from sibling tools like polymarket_arbitrage by specifying multi-venue comparison. The verb 'Cross-venue spread' precisely describes the action and resource.

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 describes two modes (topic and explicit) with specific examples. Warns that most pre-mapped topics are not tradeable and provides safety fields to check. Tells when to use each mode and what to expect, including cases where spread is meaningless.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety is clear. The description adds the returned fields but no additional behavioral context beyond what annotations provide.

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

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

The description is a single sentence that front-loads the core action and resource, 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 (no parameters, no output schema) and rich annotations, the description sufficiently covers what the tool returns, making it complete for an agent to understand.

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

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

The tool has no parameters, so the description does not need to add semantics. Schema coverage is 100% with no parameters, baseline is 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 gets a random Yu-Gi-Oh! TCG card with full details. It distinguishes from siblings like get_card (specific card) and search_cards (filtered search) by emphasizing randomness.

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 for fetching a random card but does not explicitly state when to use vs. alternatives or when not to use. No exclusions or comparison to siblings are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint. Description adds context on scoping and pairing with remember/forget, which is valuable beyond annotations.

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

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

Three sentences, no fluff. Front-loaded with action, then usage context, then scope and pairing. Every sentence adds value.

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

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

For a simple retrieval tool with one optional parameter and good annotations, the description fully covers purpose, usage, and behavior. No gaps.

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

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

Schema coverage is 100% with property description. Tool description reinforces behavior of omitting key to list all. Baseline 3 appropriate as schema does heavy lifting.

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

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

Description states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' Clearly identifies verb+resource, and distinguishes from siblings like 'remember' and 'forget'.

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

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

Provides explicit use cases: 'look up context the agent stored earlier...without re-deriving it from scratch.' Notes scoping and pairing with remember/forget. Does not explicitly exclude cases but is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds behavioral details: the effect of mark_read (next call shows only newer events) and the structure of returned alerts. 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 concise (3-4 sentences), front-loaded with the main purpose, and efficiently provides all necessary information without redundancy.

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

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

Given the simple read-only nature, strong annotations, and no output schema, the description fully covers what the tool returns, how to filter, the mark_read behavior, and alternative access, making it complete.

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

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

Schema coverage is 100%, so baseline is 3. The description explains the effect of mark_read and mentions filtering by type and since, but does not elaborate on limit or unread_only beyond schema descriptions. Adequate but not exceptional.

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

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

The description clearly states the tool retrieves recent alerts from the subscription feed, specifies key fields (source, citation_uri, raw payload), and differentiates from sibling tools like list_subscriptions or subscribe by focusing on fetching fired 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?

The description provides usage context: filtering by type and since, marking events as read, and notes that polling works fine. It also mentions an alternative GET endpoint for scripts/dashboards. It could be stronger with explicit when-not-to-use guidance relative to 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?

The description adds significant behavioral context beyond annotations: it explains the fan-out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), mentions the PatentsView API sunset causing soft-fail, and details the 'since' parameter format. Annotations already declare readOnlyHint, idempotentHint, etc., and the description aligns without contradiction.

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

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

The description is fairly long but well-structured: it starts with query examples, then describes the core function, lists data sources with fallback logic, explains parameter formats, and ends with an alternative tool suggestion. Almost every sentence adds value, though it could be slightly more concise.

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

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

For a tool with no output schema, the description fully explains the return format: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It also covers data source limitations (USPTO soft-fail due to API sunset) and parameter constraints. All aspects are addressed.

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 3 parameters described in schema), so baseline is 3. The description adds extra value by providing detailed examples for 'since' (ISO date and relative shorthand with specific examples like '30d', '1y'), clarifies that 'value' accepts ticker or CIK, and confirms 'type' is only 'company'. 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 it's a 'change feed for a company in the last N days/weeks/months' and provides multiple example query phrases like 'What's new with X' and 'latest on Y'. It explicitly distinguishes from the sibling tool 'entity_profile' by stating when to use that instead.

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

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

The description explicitly says 'Use entity_profile instead when you want the static profile...' providing a clear alternative for a different use case. It also implies guidance by listing what the tool does (dynamic updates) and what it doesn't (static profile).

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

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

Annotations provide idempotentHint=true and destructiveHint=false. The description adds significant context: persistence details (authenticated vs anonymous durations), key-value scoping, and lifecycle pairing. This goes well beyond what annotations alone provide.

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

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

The description is a single focused paragraph that front-loads the purpose, then gives usage guidance, then details, with zero fluff. Every sentence is 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?

Despite having no output schema, the description covers the tool's role, persistence behavior, and relationship to sibling tools (recall, forget). It is complete for a simple storage 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 clear descriptions for both key and value. The description echoes the schema examples but does not add new semantic detail beyond reinforcing the examples.

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

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

The description clearly states the verb ('Save'), the resource ('data the agent will need to reuse later'), and the context ('across this conversation or across sessions'). It distinguishes from siblings like 'recall' and 'forget' by positioning itself as the storage action.

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

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

The description explicitly tells when to use: 'when you discover something worth carrying forward.' It also mentions pairing with recall and forget, though it does not elaborate on when not to use or alternatives beyond those siblings.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by stating that each call 'cascades through several lookup endpoints internally' and that using this tool 'replaces 2-3 manual lookups.' Additionally, it details the return fields for each type (ticker, CIK, RxCUI, etc., with citation URIs), going well beyond the annotations.

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

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

The description is substantive and front-loaded with example queries, making the purpose immediately clear. While it is somewhat lengthy, every sentence serves a purpose—adding examples, usage guidance, behavioral insights, and return value details. A slight trim could improve conciseness, but it remains highly effective.

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

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

Given the absence of an output schema, the description compensates by clearly explaining the return values (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). With annotations covering safety and idempotency, and the description covering inputs, outputs, and usage, the tool is fully specified 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%, and the description enriches the meaning of both parameters. For 'type,' it enumerates the supported values and explains what each returns. For 'value,' it provides specific examples of acceptable inputs (ticker, CIK, name for company; brand/generic for drug). This adds significant context 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 starts with concrete user queries ('What's the ticker for…', 'find the CIK for…') and clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' This specifies verb (resolve) and resource (names to IDs), and the supported types (company, drug) distinguish it from sibling tools like 'entity_profile' or 'compare_entities'.

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

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

The description explicitly advises: 'Use FIRST whenever you have a name but need an ID.' This provides clear guidance on when to use the tool. Although it does not explicitly state when not to use or list alternatives, the sibling tool names (e.g., 'entity_profile') imply other options for different needs.

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

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

Annotations already declare readOnly, idempotent, openWorld. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. No contradiction.

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

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

Concise, front-loaded, three sentences. No redundancy. 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?

Complete for a comparison tool with robust annotations and schema. Description covers output (ranked list with metrics) and use case. No gaps given no 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%, so baseline 3. Description adds value beyond schema: explains that first entity in 'entities' is the subject for narrative, and gives default model info. Enhances understanding.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities'. Clearly distinguishes from sibling 'ai_visibility_check' which likely handles single entity. Includes example use case.

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

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

Explicitly states it's 'useful for competitive AI-marketing audits' with an example question. Implies alternative is using 'ai_visibility_check' for single entity, but doesn't explicitly mention 'when not to use' or name the sibling.

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 and idempotent. Description adds behavioral details: bundlephobia first measurement can take 5-30s, sources_failed if timeout, partial failures still return data. 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?

6 dense sentences, each essential: purpose, use cases, ecosystem, output summary, failure mode. Front-loaded with the composite check metaphor. No wasted words.

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

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

Covers all relevant aspects: two external sources, behavioral constraints, output structure, ecosystem limitation, and graceful degradation. Without output schema, the description lists the output block fields, making it complete for agent decision.

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. Description adds extra context: scoped packages accepted, version defaults to latest when omitted. This adds value beyond schema.

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

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

The description clearly states a composite check for npm packages using deps.dev and bundlephobia, with a specific verb ('scan') and resource ('npm package'). It distinguishes from siblings by specifying NPM-only ecosystem and listing output fields.

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...' with concrete queries, and contrasts with other ecosystems via deps.dev:version directly. Also notes partial failures and graceful degradation.

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 value by confirming it returns names, types, descriptions, ATK/DEF, attributes, archetypes, images, and TCGplayer prices. No contradictions. Could mention pagination behavior, but not essential.

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

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

Two sentences: first states functionality, second lists outputs. No redundant information, efficiently structured and front-loaded.

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

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

Given no output schema, the description adequately mentions return fields. Parameter descriptions are thorough in schema. Missing details like default sort or max offset are minor. Overall complete for a search tool.

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

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

Schema coverage is 100% with descriptions for all 8 parameters. The description mentions fuzzy match but does not add significant meaning beyond what schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states 'Search Yu-Gi-Oh! TCG cards by name (fuzzy), card type, attribute, monster race/type, archetype, or level' and lists return fields. It distinguishes from siblings like 'get_card' and 'random_card' by focusing on search with multiple filters.

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 what filters are available but does not explicitly state when to use this tool versus alternatives (e.g., get_card for exact card lookup, random_card for random selection). It provides clear context but lacks exclusions or when-not guidance.

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

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

Annotations already declare safe, idempotent, read-only behavior. Description adds rich details not in annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), similarity (cosine), max input length with truncation behavior, and offset inclusion for quote verification. 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?

Concise at three sentences, front-loaded with core purpose. Each sentence adds distinct value (purpose, usage guidance, technical details). No wasted words; efficiently 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?

No output schema, but description explains return type (top-N passages with offsets and scores) and mentions truncation behavior. Pairs well with sibling. Complete for a tool of this complexity with only three parameters.

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

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

Schema coverage is 100%, but description adds beyond: explains text as document to search, provides example queries for the query parameter, states default and range for limit. Also adds context about embedding and chunking, enhancing parameter understanding.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifies the action (retrieve passages), the resource (text), and the context (inside a record). It distinguishes from sibling ask_pipeworx_grounded by mentioning pairing, making 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 when to use: when the record is too large for the prompt. Explains benefits (saves context, returns relevant passages with offsets for verification). Also guides pairing with ask_pipeworx_grounded, covering when-not 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?

Adds significant behavioral context beyond annotations: requires OAuth, no anonymous, delivery channel limitations (SMS cap, webhook auto-disabled), and security details (signing secret returned once, HMAC signature). Aligns with idempotentHint and non-destructiveHint.

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

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

Well-structured, front-loaded with main action and return value. Every sentence adds value, though slightly long. Could be more concise but not wasteful.

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?

Very complete for a complex tool with nested objects, multiple subscription types, and delivery options. Covers prerequisites, constraints, and return value despite no 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 has 100% coverage (baseline 3). Description adds detailed examples and constraints for type-specific params and delivery options (e.g., phone verification, 10/day cap, webhook behavior), enhancing understanding 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?

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides when-to-use context (monitoring live data) and prerequisites (Pipeworx OAuth account, not anonymous/BYO). Does not explicitly exclude alternatives but gives enough context to infer appropriate usage.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds that it returns live-catalog examples with tool+argument shapes, and it's an onboarding entry point—providing valuable behavioral context beyond annotations.

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

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

The description is comprehensive but slightly verbose; it front-loads with common phrases and packs detailed info. Every sentence adds value, but could be slightly trimmed without losing clarity.

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

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

Given one optional parameter, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, and what results to expect—making it complete for an agent.

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

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

Schema covers 100% with clear description for 'topic'. The tool description adds 'call with no arguments for the full spread' and explains the effect of passing topic, enriching parameter understanding.

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

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

The description clearly states the tool returns category-bucketed example questions for 'what can I ask Pipeworx', lists the categories, and distinguishes it as an onboarding entry point, separating it from sibling tools like ask_pipeworx or entity_profile.

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 this FIRST when you do not yet know what Pipeworx can do for you', providing clear usage context. It also explains optional topic filtering and when to omit arguments.

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

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

Discloses that 'the row is deactivated (not deleted)' so historical events remain available, adding behavioral context beyond annotations which already indicate non-destructive behavior.

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

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

Two concise sentences, each serving a clear purpose: action/ownership and side-effect.

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

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

With one required parameter, no output schema, and clear annotations, the description fully covers purpose, constraints, and post-condition.

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 100%, description adds 'by id' and notes the id comes from 'subscribe', providing useful context beyond the schema's 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?

Clearly states 'Cancel a subscription by id' – a specific verb and resource, distinct from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly notes ownership enforcement: 'you can only cancel your own subscriptions', guiding when to use and when not. Also mentions availability of historical events via 'recent_alerts'.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, but the description adds substantial behavioral context: it details the return fields (verdict, structured form, actual value with citation, percent delta), explains the underlying data source (SEC EDGAR + XBRL), and highlights efficiency (replaces 4-6 calls). No contradictions with annotations.

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

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

The description is front-loaded with examples and purpose, then covers scope, returns, and efficiency. It is somewhat lengthy (5 sentences) but each sentence adds value. Could be trimmed slightly, but overall well-structured.

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

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

For a tool with one parameter and no output schema, the description provides thorough context: examples, supported claim types, return format, data source, and efficiency benefits. It fully compensates for the missing output schema and leaves no key gaps.

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

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

The input schema has 100% description coverage for the single required parameter 'claim', with a clear natural-language description. The tool description reinforces this with example formats but does not add substantive new semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description uses specific verbs like 'verify', 'check', 'confirm or refute' and clearly identifies the resource as 'natural-language claim verification against authoritative sources'. It provides example queries and distinguishes itself by specifying supported claim types (company-financial claims) and mentioning it replaces multiple sequential calls, thus differentiating from sibling 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 states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also delimits scope with 'v1 supports company-financial claims...', giving clear context for appropriate use. However, it does not explicitly exclude alternative tools, which would warrant a 5.

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