trivia

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

Annotations already declare safe, idempotent, read-only nature. Description adds cost implications (free default, key needed for Anthropic) and return format details. No contradictions.

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

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

Three sentences, front-loaded with primary action and outcomes. No wasted words; every sentence adds value.

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

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

With 4 fully documented parameters and annotations covering safety, the description provides return structure and key behavioral details, making it complete for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining default model behavior, optional key usage, and context disambiguation purpose.

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

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

Clear verb ('probe'), specific resource ('LLMs'), and outcome ('score visibility 0-100 per model'). Distinct from sibling tools like ask_pipeworx and 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?

Explicitly states use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide the Anthropic key. Lacks explicit when-not-to-use or alternative references, but strongly implies usage context.

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

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

Adds context beyond annotations: details about routing to 4476 tools, argument filling, stable citation URIs, and fast response. Could be more explicit about failure modes or response limits.

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

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

Front-loaded with key 'PREFER OVER WEB SEARCH' directive, followed by concise list of domains, examples, and escalation paths. No superfluous sentences, efficient for an agent.

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 the tool's role, input, and output format (structured answer with citations). Lacks details on error handling or response structure without output schema, but sufficient for most 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% with clear descriptions of all parameter aliases. The description adds value by explaining natural language input and showing examples, going beyond the schema alone.

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

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

The description clearly defines the tool as a router for factual queries across structured sources, distinguishes it from siblings like ask_pipeworx_grounded and deep_research, and provides specific examples of use cases.

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

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

Explicitly states when to use (prefer over web search for factual questions) and when not to use (step up to alternatives for hallucination-resistant or broad queries), with clear examples and context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral detail: the internal process of routing, tool selection, data fetching, extraction using only tool results, and explicit refusal reasons. 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 purpose and structured logically: purpose, process, return format, usage guidance. While somewhat long, every sentence adds value. Slightly verbose but justified by complexity.

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

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

Given the tool's complexity (4,476 tools across 1127 sources, high-stakes usage), the description comprehensively covers purpose, internal process, return format with evidence and refusal reasons, and usage guidelines. No output schema exists, so the description compensates fully.

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

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

Schema coverage is 100% with all aliases documented. The description adds little beyond schema for parameters, only clarifying that multiple aliases are accepted and the purpose of the parameter. Baseline 3 is appropriate as schema carries the burden.

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

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

The description clearly states it is a hallucination-resistant answer mode for high-stakes reads, specifying the verb 'ask' and resource 'Pipeworx' with a grounded mode. It distinguishes from sibling tool 'ask_pipeworx' by emphasizing the grounded behavior.

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

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

Explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also advises preferring ask_pipeworx for casual lookups and mentions cost trade-off.

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 thoroughly discloses behavior: fan-out, classifiers, response shapes, resolver contract, parent event extraction, news fallback, safety short-circuits, and cancellation rules. It adds significant value beyond annotations (readOnly, idempotent, etc.) and does not contradict them.

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

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

The description is dense but every sentence adds value. It could be more structured (e.g., separated sections), but given the complexity, it remains relatively concise and front-loaded with key purpose and usage.

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

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

Despite no output schema, the description fully explains return shapes (market, analysis, evidence), resolver details, parent event fields, news fallback, safety mechanisms, and cancellation risk. It covers all major edge cases and practical considerations.

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 coverage, the description adds substantial meaning: explains accepted formats for 'market', values and defaults for 'depth' (quick vs thorough), and behavior of 'include_raw' (summarized vs full payloads). Examples and edge cases are provided.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, and specifies input types (slug, URL, question text). It lists specific use cases ('should I bet on X', etc.), distinguishing 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 explicitly states when to use the tool ('Use for...'), and provides detailed guidance on inspecting resolver fields and safety mechanisms. However, it does not explicitly exclude situations or compare to sibling tools, though 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 idempotent, read-only, open-world, non-destructive. The description adds behavioral details: results sorted by primary metric, returns citation URIs, handles off-calendar fiscal years. 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 front-loaded with example queries and preference, then details. Every sentence adds value without redundancy. Approximately 6 sentences, well-organized.

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

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

No output schema exists, but the description explains return format: paired data + citation URIs, sorted by metric. It covers both types, data sources, and special cases (fiscal year handling). Complete for an agent to invoke correctly.

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

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

Schema coverage is 100% (baseline 3). The description adds significant meaning: explains that type='company' pulls 10-K data with fiscal year handling, and type='drug' pulls FAERS and FDA data. It clarifies 'values' as tickers/CIKs or drug names, exceeding schema.

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

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

The description explicitly states the tool's purpose: side-by-side comparison of 2–5 companies or drugs in one parallel call. It distinguishes from siblings by advocating against sequential single-pack lookups and stating it replaces 8–15 sequential calls.

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

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

The description clearly tells the agent to prefer this tool over sequential lookups when comparing entities. It provides context on entity types and data sources but does not explicitly exclude other use cases, though the preference statement is strong.

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

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

Discloses many behavioral traits not covered by annotations: account requirement, paid plan for thorough, decomposition into facets, parallel routing to 4476 tools, return format with evidence and gaps[], expected 15-60s, and behavior when topic not in catalog. No contradiction with annotations.

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

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

The description is well-structured and efficient. It front-loads critical info (account requirement), then explains functionality, then provides usage comparisons, and ends with examples. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description sufficiently explains the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation, and gaps[]). Given the tool's complexity, the description covers all necessary aspects for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the depth enum values (quick=3, standard=5, thorough=8) and re-emphasizing that question can be broad/multi-part. It also adds the important constraint that thorough requires a paid plan.

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 that the tool performs grounded multi-source research across 1127 structured data sources, decomposing questions into facets and routing to tools in parallel. It contrasts with siblings like ask_pipeworx, making the purpose distinct.

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

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

Provides explicit guidance: best for broad/multi-part questions over structured data, for a single lookup use ask_pipeworx, for breaking/news topics prefer ask_pipeworx. Also mentions account requirements and 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 that it returns top-N tools with schemas ready to call, going 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?

Single paragraph packed with purpose, usage, and output details. Could be slightly more concise but overall well-structured and informative.

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

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

Given the tool's role as a discovery tool among many siblings, the description fully explains its purpose, when to use, and what it returns. No output schema but return structure is described adequately.

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

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

Schema coverage is 100% with descriptions. Description reinforces usage of 'query' parameter with natural language examples and aliases, adding value.

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

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

The description clearly states it discovers tools by describing data or task, listing many domains. It distinguishes itself from sibling tools by being a search/discovery tool.

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 'Call this FIRST' when you have many tools and want to see the option set. Provides clear context for when to use, though does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. Description adds useful details: fans out across multiple sources, mentions patent soft-fail due to API sunset, GDELT→GNews fallback, and specific return fields. No contradiction.

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

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

Description is somewhat long but front-loaded with examples. Every sentence adds value, though some minor redundancy could be trimmed.

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

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

No output schema, so description must explain returns. It thoroughly lists all return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI). Complete for a profile 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% and parameter descriptions are clear. Description reiterates value format and adds future context for type enum. Adds marginal value over schema.

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

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

Description uses specific verb 'profile' and resource 'US public company', lists many example queries, and distinguishes from siblings like deep_research and resolve_entity.

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 'ALWAYS PREFER over chaining single-pack lookups for holistic view' and specifies when to use resolve_entity instead (for names). Clear when-to-use and when-not-to-use.

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

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

The description notes the destructive nature ('delete', 'clear sensitive data') beyond the annotation's destructiveHint:true. It adds context about when deletion is appropriate, though it does not detail permanence or effects on related memories.

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: first states purpose, second provides usage context. No unnecessary words or repetition.

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

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

For a simple delete tool with one parameter and no output schema, the description covers what, when, and how to use it with siblings, 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% with a description for 'key' as 'Memory key to delete'. The description adds no further parameter details beyond the schema, so 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 'Delete a previously stored memory by key', specifying the verb (Delete) and resource (stored memory). It distinguishes from siblings by mentioning '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?

The description provides explicit scenarios for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also suggests pairing with siblings but lacks explicit exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds that it fetches the page, extracts elements, and emits markdown, which aligns well with annotations and provides extra behavioral context beyond the structured fields.

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

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

The description is a single efficient paragraph of three sentences, front-loaded with the main purpose, and every sentence adds value 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 tool's simplicity, two parameters, and rich annotations, the description adequately explains the output format and usage. It does not address error cases or site limitations but is sufficient for normal 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 description coverage is 100% with both parameters described. The description does not add new information beyond what the schema already provides (e.g., default 25, max 50 for max_links). Baseline 3 is appropriate.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, listing specific steps and use cases. It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on file generation rather than presence scanning.

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

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

The description lists explicit use cases (client indexing, drafting, auditing competitor) but does not explicitly mention when not to use or alternative tools. The context is clear but lacks exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds that it returns aggregated counts by difficulty, which is beyond the annotations. No further behavioral details (e.g., performance, limits) but adequate given the simple operation.

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?

Single sentence, front-loaded with the purpose, no extraneous words. Efficient and clear.

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 1-parameter, read-only tool with an output schema, the description fully communicates the tool's purpose and output. No gaps remain.

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

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

Schema coverage is 100% with a clear description for the 'category' parameter. The tool description does not add additional meaning beyond the schema, meeting the baseline of 3.

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

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

The description uses a specific verb ('Get') and resource ('total and per-difficulty question counts for a specific category'), clearly distinguishing it from siblings like 'get_questions' (full questions) and 'list_categories' (list of categories).

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

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

The description clearly states that it operates on a specific category, implicitly requiring a category ID from 'list_categories'. No explicit exclusions or alternatives, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that the source is the Open Trivia Database and that filters are optional, which is useful but does not significantly expand beyond annotation 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?

Two concise sentences: purpose followed by optional filters. No superfluous words, front-loaded with core action. Excellent structure.

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 rich annotations, full schema coverage, and an output schema, the description is complete for an agent to understand the tool. All key aspects (source, optional filters) are covered. The presence of an output schema means return values need not be described.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description only mentions 'category, difficulty, and question type' without adding new details, so it does not enhance parameter understanding beyond the schema.

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

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

The description clearly states the tool retrieves trivia questions from the Open Trivia Database, with optional filtering. The verb 'get' and resource 'trivia questions' are specific. It distinguishes itself from siblings like list_categories and suggest_questions by focusing on question retrieval.

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

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

The description mentions optional filters but provides no explicit guidance on when to use this tool versus alternatives like suggest_questions or get_category_stats. Given many sibling tools, more contextual hints would improve clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it lists 'all' categories and includes IDs, but does not disclose additional behavioral traits such as pagination or rate limits.

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

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

Single sentence, front-loaded with key information. Every word serves a purpose. No unnecessary detail.

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

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

Given no parameters, rich annotations, and the presence of an output schema, the description is sufficiently complete for this straightforward listing 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?

No parameters exist, so the description cannot add parameter-level meaning. With zero parameters, baseline is 4, and the description does not detract.

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

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

Description clearly states the action ('list'), resource ('trivia categories'), and included information ('their IDs'). It is specific and distinct from sibling tools like 'get_category_stats' or 'get_questions'.

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

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

No explicit guidance on when to use this tool versus alternatives. Usage is implied as a prerequisite for category-specific tools, but no exclusions or when-not advice is 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=true and destructiveHint=false, so the description's primary contribution is listing return fields. It does not contradict annotations, and it adds context about active subscriptions and typical usage. The behavioral burden is mostly carried by 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 states purpose and return fields, second gives usage guidance. Every sentence adds value, no filler. Front-loaded with key information.

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

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

Despite no output schema, the description lists all return fields. The single parameter is fully documented. It covers the tool's purpose, usage scenarios, and output. Minor omission: no mention of pagination or limits, but for a simple list tool this is adequate.

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 well-described boolean parameter. The description does not add new parameter details but reinforces the context of 'active subscriptions' which relates to the default behavior. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the exact return fields (id, type, params, created_at, last_fired_at, fire_count). This is a specific verb+resource combination, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' It provides context for when to use the tool, though it does not explicitly exclude alternative tools or mention when not to use it.

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

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

The description discloses rate limits (5 per identifier per day), quota impact (free, doesn't count against tool-call quota), and how feedback is used (daily digests affect roadmap). These details go beyond the annotations, which only indicate non-read-only and non-destructive.

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 5 sentences, each providing essential information: purpose, use cases, guidance, team impact, and limits. No superfluous content; front-loaded with 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?

The description comprehensively covers what the tool does, when to use it, how to construct feedback, and behavioral limits. It does not describe the return value, but for a feedback tool, that is less critical.

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

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

The input schema covers all parameters (100% coverage), but the description adds valuable context: it advises describing issues in terms of Pipeworx tools/packs and not pasting user prompts. This enhances the schema's guidance.

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

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

The description clearly states the tool's purpose: sending feedback to the Pipeworx team about bugs, missing features, etc. It distinguishes itself from sibling tools by being the only feedback tool.

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 specifies when to use (bug, feature, data_gap, praise) and provides guidance on what not to include (end-user's prompt). It does not list alternatives because no sibling feedback tool exists, but the context is clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by disclosing data source (CF analytics-engine), privacy (no PII), and caching (5min-1h), which are 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 concise, clearly structured into purpose, use cases, and technical notes, with no redundant information.

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

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

Given the tool's simplicity and rich annotations, the description covers all essential aspects: purpose, usage, data source, privacy, and caching. It does not describe return format, but no output schema is expected.

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% (one parameter with enum). The description adds semantics by explaining trade-offs between short and long windows, enhancing understanding beyond the enum labels.

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

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

The description clearly states what the tool returns (top tools, top packs, call volume) and provides three specific use cases, making the purpose specific and actionable.

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

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

The description explicitly lists three scenarios for when to use the tool, but does not mention when not to use or suggest alternatives, which is acceptable given the large set of 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 (readOnly, openWorld, idempotent) are consistent. Description adds detailed algorithmic steps (monotonicity checks, partition_sum, fill check against CLOB depth) and constraints (skipped_low_similarity, placeholders_filtered).

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?

Dense and well-structured, but slightly verbose. Front-loaded with requirement, then modes, then details. Every sentence adds value, but could be streamlined slightly.

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

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

No output schema, but description fully explains response fields (opportunities, partition_check, fill_check) and covers edge cases (no args fail, skipped_low_similarity, placeholders). References sibling for deeper 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 coverage is 100%, but description adds rich context: examples of slugs, how modes differ, and what happens with each parameter (e.g., Jaccard filter, partition filter).

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 arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes between event and topic modes, and provides examples. Differentiates from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicitly requires one of event or topic, explains when to use each mode, mentions semantic anchor (Jaccard >=0.30) and partition filter. Points to 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, but the description adds extensive behavioral context: caching behavior ('Cached 1h at the KV level'), detailed model calculations (e.g., lognormal barrier, GDELT ratio, partition_overround with sport-specific α), and edge properties (edge_pp_net after slippage, Kelly fractions, 24h-move warning). No contradiction with annotations.

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

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

The description is verbose and densely technical, but well-structured with clear sections (by_segment segments, response top-level, diagnostics). The first sentence effectively front-loads the purpose. Every sentence provides critical information for a tool with 9 parameters and 5 model families, making the length justified.

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

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

Despite lacking an output schema, the description thoroughly details the response structure: top-level fields (by_segment, fed_candidates, _diagnostics) and per-opportunity attributes (edge_pp_net, kelly_fraction, market fields, 24h-move warning). Parameters are fully explained with defaults and usage tips. No gaps remain.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter names and basic descriptions. For example, min_kelly explains 'Skips opportunities that are too small to bet sensibly', min_partition_leg_kelly clarifies how partition arbs are handled differently, and max_spread_pp/min_liquidity provide actionable guidance ('Set to 2 to require tight books', 'Set to 5000 to drop thin-book opportunities').

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 ('Scan top Polymarket markets') and the resource ('opportunities where Pipeworx data disagrees with market price'). It distinguishes from siblings by covering multiple model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) that are not present in other tools like polymarket_arbitrage or polymarket_edge_tracker.

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 ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') but does not explicitly state when to use this tool vs siblings like polymarket_arbitrage or polymarket_edge_tracker. No exclusions or alternative recommendations are given, relying on implied 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?

The description provides extensive behavioral context beyond annotations. It details the response structure (tracked, expired, snapshot_dates arrays), explains how decay and trend are computed, clarifies that negative edge_pp_net means SELL YES, and discloses that history depends on snapshot TTL and when snapshotting started. Annotations already indicate read-only, idempotent, and non-destructive behavior, so the description adds value 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 thorough and well-structured, with the core purpose stated upfront followed by detailed response fields and limitations. While every sentence adds value, the description is somewhat lengthy. It could be slightly more concise without losing information, but it remains efficient and well-organized.

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

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

The tool has no output schema, so the description must fully explain the return value, which it does by detailing the three arrays (tracked, expired, snapshot_dates) and their fields, including edge_pp_net time-series, first_seen, trend, decay, lifespan, etc. It also covers limitations like history depth and computation frequency. This makes the description complete for agent decision-making.

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

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

Both parameters (days, window) are fully described in the input schema with defaults and constraints. The description reiterates defaults and adds a clamp note for days, but does not provide significant additional meaning beyond what the schema already offers. With 100% schema coverage, the baseline is 3, and the description does not elevate it further.

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 that this tool provides edge persistence and decay telemetry, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from the sibling tool polymarket_edges by focusing on time-series analysis rather than current edge values, and explicitly contrasts fresh wide edges with old ones, making the purpose specific and unambiguous.

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

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

The description explains when to use the tool: to analyze edge persistence over time. It mentions limits like the 60-day TTL and that decay is based on daily closes, not intraday. However, it does not explicitly state when NOT to use it or directly name alternatives like polymarket_edges for current edges, though it is implied. The usage context is clear but lacks explicit exclusions.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about partial basket fills converting arbs into unhedged directional positions. This adds value beyond what annotations provide, without contradicting them.

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

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

The description is long and detailed, using bold for structure to separate modes and requirements. It is front-loaded with the core purpose. However, it is somewhat verbose; nearly all sentences are necessary given the complexity, but it could be tightened slightly.

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

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

Given the complexity of the tool (two modes, no output schema), the description thoroughly explains return values, risks, and usage context. It covers single-market and basket modes, all fields returned, and warnings about thin books and directional risk. It compensates well 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?

Schema description coverage is 100% (all parameters documented in schema). The description adds meaning by explaining default values, the difference between single-market and basket mode for each parameter, and the interpretation of 'size_usd' (spend, target proceeds, settlement notional). It also describes the auto-default for 'side' in basket mode. This goes beyond the schema alone.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', naming the verb 'check' and resource 'edge'. It distinguishes between single-market and basket modes, and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by specifying usage before acting on their signals.

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 risks of not using it (theoretical overround not capturable, partial basket fills leading to unhedged positions). It also states the requirement for either 'market' or 'event' parameter. It does not explicitly list when not to use, but the threshold implies smaller trades may not need it.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds detailed behavioral context: spread calculation, compatibility warnings, temporal alignment, skipped cross-type/subtype counters. 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?

Well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Content is dense and valuable, but slightly lengthy. Could be trimmed without losing crucial info.

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 compensates with detailed explanation of response fields. Covers all necessary aspects for a cross-venue spread tool including edge cases and limitations.

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 context: topic is a shortcut for 10 pre-mapped macros, explicit parameters override the topic side. Provides 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?

Clearly states it computes cross-venue spread between Kalshi and Polymarket. Distinguishes from sibling 'polymarket_arbitrage' by being cross-venue. Specifies two modes (topic shortcuts and explicit pairings).

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

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

Provides explicit guidance on when to use each mode, explains response contents, safety fields, and when spreads are meaningful. Warns that pre-mapped topics may not always yield tradeable spreads.

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, destructiveHint. Description adds consistency by stating 'retrieve' and 'list' without mutation. Does not add new behavioral insight beyond what annotations provide, so score reflects minimal added 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?

Description is front-loaded with the primary action and includes essential use cases in subsequent sentences. Slightly verbose with multiple examples but no fluff. Very efficient.

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

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

Given no output schema, the description explains what to expect (value or list of keys) and mentions scope. For a simple read tool with one optional parameter, this 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%, and the parameter description already explains 'omit to list all keys'. The tool description reinforces this but doesn't add new semantic detail. Baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'retrieve' and resource 'value previously saved via remember'. It distinguishes from siblings by naming '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?

Explicitly says when to use: 'look up context the agent stored earlier'. Provides concrete examples (ticker, address, research notes). Names alternatives: 'remember' and 'forget'. Explains scoping to identifier.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds context about mark_read side effect (flags events as read), output structure (source, citation_uri, raw payload), and polling 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?

Four sentences, no redundancy. Front-loaded with purpose, then key behaviors, filtering, and alternative access. 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?

No output schema, but description explains return fields. Annotations cover side effects. Parameters fully explained. Adequate for a read-only polling tool without complex return structure.

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%, baseline 3. Description adds value by providing examples ('sec_8k'), clarifying ISO timestamp format, and explaining mark_read purpose, exceeding schema-only info.

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

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

Description clearly states 'Pull fired events from your subscription feed' with specific verb and resource. It differentiates from sibling tools like list_subscriptions by focusing on events, not subscription management.

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

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

Provides clear usage context: filtering options, mark_read flag, and polling suitability. Mentions alternative access for scripts/dashboards, but lacks explicit guidance on when not to use this tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world. The description adds significant behavioral details: fans out to SEC EDGAR, GDELT→GNews, USPTO with soft-fail; accepts ISO dates or relative shorthand; returns structured changes with URIs.

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 and well-structured, front-loading examples. It is slightly long 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?

Given the complexity (multiple sources, fallback, window formats), the description covers all necessary aspects: source behavior, return structure (changes grouped by source, total_count, URIs), and error handling. No output schema needed as description 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%, but the description adds meaning: explains `since` format (ISO or relative shorthand like '7d') and typical monitoring suggestion; clarifies `value` as ticker or CIK; confirms `type` only supports 'company'.

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

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

The description clearly states the tool retrieves a change feed for a company in a recent time window, fanning out to multiple sources. It includes example user queries that distinguish its purpose from sibling tools like 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 tells when to use this tool vs. alternatives: 'Use entity_profile instead when you want the static profile'. Also describes fallback behavior between GDELT and GNews based on rate limits or errors.

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 (idempotentHint=true), the description adds important behaviors: key-value pair scoped by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

The description is concise yet comprehensive, front-loaded with the main purpose, followed by usage, storage details, and pairing hints. Every sentence adds value without unnecessary words.

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

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

For a simple key-value store tool, the description covers purpose, usage, storage lifetime, scoping, and pairing with siblings. Annotations and schema provide additional safety and parameter info, 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% with good parameter descriptions. The description adds semantic value by providing examples of keys and values (e.g., 'resolved ticker', 'target address'), enriching understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It specifies the verb ('save'), resource ('data'), and distinguishes from sibling tools such as 'recall' and 'forget'.

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

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

The description provides explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also mentions pairing with 'recall' to retrieve and 'forget' to delete, offering clear when-to-use and 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context by noting internal cascading through multiple lookup endpoints and providing citation URI formats, going beyond what annotations convey.

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

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

The description is moderately long but each sentence serves a purpose, covering examples, usage, supported types, and internal behavior. It is front-loaded with examples, though a minor trim could improve conciseness without losing critical info.

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, yet the description thoroughly explains return values for both entity types, including identifiers and citation URIs. Combined with usage guidance and internal behavior disclosure, it provides all necessary context for an AI agent 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?

Though schema coverage is 100%, the description significantly enriches parameter meaning. For 'type,' it details what each enum value returns (e.g., ticker, CIK, RxCUI). For 'value,' it provides concrete examples (AAPL, 0000320193) and clarifies input flexibility, adding substantial 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 starts with clear example queries and explicitly states the tool resolves names to canonical IDs. It distinguishes between 'company' and 'drug' types with specific return formats, making the purpose unambiguous and distinct from siblings.

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

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

The description advises 'Use FIRST whenever you have a name but need an ID,' providing clear usage context. It also mentions that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not explicitly compare to siblings like entity_profile or search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it internally calls ai_visibility_check for each entity, treats the first entity as the 'subject', and returns a ranked list with metrics. No contradiction with annotations.

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

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

Three sentences, front-loaded with purpose, followed by mechanism and use case. Every sentence adds value without redundancy. No fluff.

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

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

Given no output schema, the description adequately explains what is returned (ranked list with score, confidence, signal density). It also covers the entity role semantics and internal probe mechanism. Complete for a comparative tool.

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

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

Schema description coverage is 100%, but the description adds meaning beyond it: it explains that the first entity is the 'subject' for narrative and that context is shared across probes. This additional guidance enhances 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 uses specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource (AI visibility across entities). It distinguishes from sibling tools like ai_visibility_check by emphasizing multi-entity comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and implies when to use it (multi-entity comparison vs. single check via ai_visibility_check). However, it does not explicitly state when not to use it or name the alternative 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?

The description adds significant behavioral context beyond the annotations: it fans out across deps.dev and bundlephobia, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. This aligns with the readOnlyHint and idempotentHint 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 and front-loaded with the core purpose. Every sentence adds value, covering purpose, use cases, limitations, and return structure without fluff. It efficiently packs essential information into a single coherent paragraph.

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 thoroughly lists return fields (summary block with specific keys, per-advisory detail, links, alternative versions) and explains error handling (partial failures with sources_failed). It gives the agent a complete mental model of the tool behavior and output.

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 have 100% schema description coverage, but the tool description enriches them by explaining how they drive the composite check (e.g., 'fans out across deps.dev and bundlephobia'). This contextualizes the parameters beyond the schema, earning a slightly higher score than baseline 3.

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 composite purpose: a one-call check for adding an npm package, covering safety, popularity, and size. It specifies the verb 'scan' and the resource 'dependency', and distinguishes itself from sibling tools by detailing its unique multi-source aggregation.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also explains when not to use it (non-npm packages) and how alternatives work, including a note on partial failures and timeout behavior.

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 embedding model (BGE-base-en), similarity method (cosine), window size (500-char), char limit (200K) with truncation flag, and return values (offsets, scores). 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?

Single paragraph packs purpose, usage, pairing, and technical details without excessive length. Could be slightly more structured but very 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?

Without output schema, description still explains return values (passages, offsets, scores) and truncation behavior. Complete for a search tool with these 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 has 100% coverage with good descriptions. Description adds extra context like char limit for text and query examples, going beyond schema.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource, and distinguishes from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says when to use (when record too big for prompt) and mentions pairing with ask_pipeworx_grounded for grounded grounding, providing clear 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 discloses important behavioral traits: returns subscription ID, requires OAuth, has SMS rate limits (10/day), webhook auto-disable after 10 failures, and secret delivered once. Annotations already provide idempotentHint (not contradicted) and readOnlyHint false, so description adds value 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 well-structured with a clear purpose statement followed by requirements, types, and delivery details. It contains some redundancy with schema descriptions but each sentence adds context. It is not overly verbose.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers key aspects: subscription creation, return value, authentication, type-specific params, and delivery channel options. It lacks error details but is sufficiently complete for agent invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: detailed examples for each supported type (sec_8k, polymarket_edge, fred_series) and delivery constraints. However, it omits two schema-enumerated types (patent_grant, clinical_trial), creating a gap.

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 and returns a subscription ID. It uses a specific verb ('Create') and resource ('subscription') and differentiates from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context: requires a Pipeworx OAuth account and lists supported types. However, it does not explicitly state when to use this tool versus alternatives (e.g., list_subscriptions for viewing existing subscriptions). The guidance is implicit but clear enough for an AI agent.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral context: returns category-bucketed examples drawn from a live catalog, and includes tool+argument shape, which goes beyond annotation hints.

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

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

Description is somewhat lengthy but well-structured, front-loaded with common questions. Every sentence serves a purpose, though a slight trim could improve conciseness.

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

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

Despite no output schema, the description explains the return structure (category-bucketed examples with tool+argument shape) and covers the single optional parameter. Context for a low-complexity tool is fully adequate.

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

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

Schema coverage is 100%, but description adds meaning: 'topic' is optional, lists valid foci (finance, pharma, etc.), explains behavior when omitted (full spread) vs. when passed (focused). This enriches 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 returns example questions about Pipeworx, organized by category, and serves as an onboarding entry point. It distinguishes from sibling tools like ask_pipeworx and get_questions by specifying it's for 'what can I ask?' and shows how to call meta-tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and instructs when to pass topic to focus. Provides clear context without needing exclusions.

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

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

The description reveals that the row is deactivated (not deleted) and that historical events remain available via recent_alerts. This adds significant value beyond the annotations, which only indicate non-destructive and idempotent.

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

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

Two sentences, front-loaded with action and immediate constraint, followed by key behavioral detail. No redundant 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 (one parameter, no output schema), the description covers ownership, effect, and relationship to another tool. Fully adequate for correct invocation.

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

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

The input schema covers 100% of parameters and provides a clear description for 'id'. The tool description does not add additional semantic information about the parameter beyond what the schema already provides.

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

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

The description uses specific verb 'Cancel' with resource 'subscription by id', clearly differentiating from siblings like 'subscribe' and 'list_subscriptions'. It explains the outcome (deactivation not deletion) and links to another tool 'recent_alerts'.

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

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

The description states ownership enforcement ('you can only cancel your own subscriptions'), which provides important context for when to use the tool. However, it does not mention when not to use it or list 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 indicate read-only, open-world, idempotent, non-destructive. The description adds valuable details: returns verdict types (confirmed, approximately_correct, etc.), structured form, actual value with citation, and percent delta, and explains it replaces 4-6 calls. No contradiction with annotations.

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

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

The description is approximately 100 words, front-loaded with key terms and examples. Every sentence earns its place—no redundancy or fluff.

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

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

With one required parameter, no output schema, but strong annotations, the description provides clear return information (verdict types, citation) and scope, making it complete for the tool's purpose.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The tool description adds value by providing examples of claim phrasing and clarifying it is natural-language, which goes 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?

The description uses specific verbs like 'verify', 'confirm or refute' and clearly states the tool is for natural-language claim verification against authoritative sources, with a focus on company-financial claims. It distinguishes itself from siblings by noting it replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies scope (company-financial claims for public US companies). While it doesn't list exclusions, the specificity provides clear guidance.

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