Color Pizza

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

The description adds significant behavioral details beyond annotations: default model is free, passing `_apiKey` enables Anthropic (BYO key with cost), and it lists return fields (score, confidence, signals, raw_response, combined view). This supplements the annotations (readOnly, openWorld, idempotent) with concrete cost and response structure info.

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

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

The description is two sentences long, front-loaded with the main action, and every sentence adds essential information (purpose, default behavior, return format, cost implication). No redundant or unclear phrasing.

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

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

Given the absence of an output schema, the description explicitly states the return structure (per-model and combined view). It covers all essential aspects: what the tool does, how to configure it (models, apiKey), optional context, and use cases. The tool is moderately complex, but the description leaves no obvious gaps.

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

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

Input schema already describes all parameters (100% coverage). The description adds value by clarifying default model behavior (Workers AI free), the conditional need for `_apiKey`, and the purpose of `context` for disambiguation. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility (0-100). It uses specific verbs ('probe', 'score') and resources ('LLMs', 'models'). It distinguishes from sibling tools like 'entity_profile' or 'scan_competitor_ai_presence' by focusing on multi-model visibility scoring.

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

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

The description provides clear context for when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly exclude alternatives or mention when not to use, but the targeted use cases are well-defined.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context about routing to thousands of tools and returning cited URIs, but does not disclose any potential behavioral traits beyond what annotations imply.

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

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

The description is well-structured: starts with a preference statement, then explains functionality, then when to use, examples, and alternatives. It is front-loaded with key information. However, it is somewhat lengthy and could be trimmed without losing value.

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

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

Given the tool's complexity (4,552 tools, 1160 sources), the description covers purpose, usage guidelines, examples, and alternative tools thoroughly. It provides enough context for an agent to know exactly when and how to invoke the tool, even without 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 coverage is 100% with descriptions for all parameters. The description adds context about accepting natural language and aliases (q, query, etc.), but the schema already documents these. No additional nuance is added beyond what the schema provides.

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

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

The description clearly states 'answers factual questions about real-world entities using structured data from 4,552 tools across 1160 sources with citations.' It distinguishes from siblings like ask_pipeworx_grounded and deep_research, 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?

Explicitly says 'PREFER OVER WEB SEARCH' and provides concrete when-to-use guidance: for factual questions with examples. It also states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions).

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 set readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: refusal reasons (not_in_source, no_tool_match, etc.), success return format (answer, evidence, confidence, source, fetched_at), and the single extra LLM call. 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 long (~150 words) but front-loaded with core purpose. Every sentence adds value, including return format, refusal reasons, and usage tradeoffs. Could be slightly more concise, but structure is clear 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?

No output schema exists, so the description thoroughly explains the return structure (answer, evidence, confidence, etc.) and all possible refusal reasons. This is complete for a complex query tool with high stakes usage.

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 6 parameters (aliases) described. The description clarifies that 'question' accepts aliases and is in natural language, adding some context beyond the schema. Baseline 3 is appropriate, and the extra detail justifies a 4.

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

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

Clearly states it is a hallucination-resistant answer mode for high-stakes reads. Specifies it extracts answer only from tool results, distinguishing it from ask_pipeworx. The verb 'ask' combined with grounded mode explicitly describes function.

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

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

Explicitly says when to use (high-stakes reads, when answer will be quoted/cited/acted on) and when not (prefer ask_pipeworx for casual lookups). Also explains the cost tradeoff (extra LLM call), providing clear decision 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 the tool as read-only, idempotent, and non-destructive. The description adds substantial behavioral details: market resolution, classification, fan-out, response structures, safety short-circuits, spread warnings, and cancellation rule risk. 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 long (~500 words) but well-structured with clear sections and bolded key terms. It front-loads the purpose in the first sentence. While not extremely concise, the length is justified given the tool's complexity and the need to cover many edge cases.

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

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

Despite having no output schema, the description thoroughly covers all aspects of the tool's behavior, including response shapes, resolver contracts, parent event extraction, news fields, safety checks, and cancellation rules. It leaves minimal gaps for an agent to be confused.

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 all three parameters are documented. The description adds significant meaning beyond the schema: e.g., the 'depth' parameter's default behavior and the 'include_raw' parameter's impact on response size. This compensates for the 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 purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet + comparison), distinguishing it from sibling tools like polymarket_arbitrage or ask_pipeworx.

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

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

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes extensive examples of fan-out for different bet types. However, it does not explicitly contrast with alternatives like polymarket_edges for multi-bet scenarios.

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

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

The description adds significant behavioral context beyond annotations: it explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, result sorting by primary metric, and citation URIs. Annotations already indicate readOnly, idempotent, non-destructive; description aligns and enriches.

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

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

The description is relatively long but well-structured with front-loaded examples. Every sentence adds value, though it could tighten redundancy in the example listing. Still, it balances completeness with readability.

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

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

For a tool with no output schema, the description adequately explains return format (paired data + citation URIs), entity types, data sources, and sorting. It provides all necessary context for an agent to use correctly and understand results.

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

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

Schema has 100% coverage with descriptions for both parameters. The description adds meaning by explaining the 'type' enum values and what data they retrieve, and clarifies 'values' array constraints and examples. It enhances understanding beyond 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 side-by-side comparisons of 2-5 companies or drugs, using natural language examples like 'Compare X and Y' and 'rank these companies'. It distinguishes itself from sibling tools by noting it replaces 8-15 sequential lookups.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries. It gives clear context for when to use, but does not explicitly mention exclusions or alternatives beyond sequential lookups.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds rich behavioral details: returns verbatim evidence with confidence, source, fetched_at, stable citation, explicit gaps[], parallel execution across 4,552 tools, and 15-60s latency. No contradiction with annotations.

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

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

The description is lengthy but highly informative and front-loaded with the critical account requirement. Every sentence provides value. Minor redundancy could be trimmed, but overall efficient given the complexity.

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

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

Despite no output schema, the description fully explains the return packet contents, limitations, and when it performs poorly (gaps[]). Covers purpose, usage, alternatives, and behavioral traits comprehensively.

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

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

Input schema covers both parameters with descriptions (100% coverage). Description adds context beyond schema: it clarifies that 'thorough' depth requires a paid plan, and that 'question' should be broad/multi-part. This extra context elevates the score above 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 it performs grounded multi-source research across 1160 structured data sources, decomposing questions into facets and returning a findings packet. It distinguishes from sibling tools like ask_pipeworx, which is for single lookups.

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

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

Explicitly advises when to use deep_research versus alternatives: use ask_pipeworx for single lookups and for breaking/current news topics. Also mentions account and plan requirements, and expected response time.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds that results include full schemas and are ready to call directly, enhancing transparency beyond annotations.

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

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

Description is somewhat lengthy due to domain list but each sentence serves a purpose. Purpose is front-loaded, structure is 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?

No output schema, but description explains what is returned (names, descriptions, schemas) and that results are directly callable. Covers essential aspects for a discovery tool.

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

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

100% schema coverage provides baseline 3. The description adds context by mentioning aliases and providing natural language examples, adding value 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 explicitly states the tool finds tools by describing data or task, listing many domains, and distinguishes it from sibling tools which query specific data sources.

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 'when to use' guidance (browsing, searching, discovering) and explicitly instructs to call this first when exploring many tools. Lacks explicit exclusion criteria or comparison to related 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?

Discloses beyond annotations that it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and notes potential soft-fails (USPTO PatentsView API sunset). The description adds context about return fields and sorting (fundamentals sorted by period_end DESC). 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?

Despite length, every sentence is informative. It front-loads example queries, then states preference, then lists return components with details. No wasted words; well-structured.

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

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

Given no output schema, the description fully explains return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and covers edge cases (patents soft-fail). It is complete for the tool's complexity.

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

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

Input schema coverage is 100% (both parameters described), so baseline is 3. The description adds value with examples ('AAPL', '0000320193') and a pointer to resolve_entity for names, which clarifies usage beyond the schema. However, it largely reiterates the schema descriptions.

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

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

The description explicitly states the tool returns a 'full cross-source profile of a US public company in ONE parallel call' and lists specific example queries like 'Tell me about X'. It distinguishes itself from siblings by noting it should be preferred over chaining single-pack lookups for holistic views.

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 when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use it (for names, use resolve_entity first) and outlines the supported inputs (ticker or CIK).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds 'Delete a previously stored memory', which aligns but doesn't add new behavioral insight beyond the annotations. No contradiction, but minimal extra 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?

Two sentences that convey the purpose, usage guidance, and relation to siblings. Front-loaded with the core action, no wasted words.

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

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

For a simple delete tool with one parameter, the description together with annotations and input schema fully covers what the agent needs to know. The sibling list provides additional context.

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

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

Schema coverage is 100% with a single 'key' parameter described as 'Memory key to delete'. The description does not add any additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description explicitly states 'Delete a previously stored memory by key', which is a clear verb+resource. It distinguishes itself from siblings by referencing 'remember' and 'recall', showing its role in the memory triad.

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

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

It provides explicit guidance on when to use ('context is stale, task is done, clear sensitive data') and mentions pairing with alternative tools ('remember and recall'), making it easy for an agent to decide.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral details: fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose and includes only necessary information without redundancy. Every sentence adds value.

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

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

Given the low complexity (2 params, no output schema), the description fully covers purpose, usage, behavior, and output format. Annotations handle safety. 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 description coverage is 100% for both parameters. The description repeats the default and max for max_links but adds no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL. It specifies the verb (generate), resource (URL), and output (llms.txt). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than visibility 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 provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor sites. While it does not explicitly state when not to use or list alternatives, the context and sibling tools provide sufficient guidance.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds context about what fields are returned (titles, descriptions, color counts, licenses), which is beyond the annotations.

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

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

Two sentences efficiently convey purpose, output, and usage guidance with no unnecessary words.

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

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

Despite no output schema, the description specifies the fields in the palette list and links it to related tools, making it fully informative for a simple discovery tool.

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

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

There are no parameters, and schema coverage is 100%. The description doesn't need to elaborate further; a baseline of 4 is appropriate for zero-parameter tools.

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 lists all available color-name lists (palettes) with specific fields, and distinguishes it from sibling tools like name_colors and search_color_names by indicating it's for discovering valid 'list' arguments.

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

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

The description explicitly tells when to use the tool: to discover valid values for the 'list' argument of name_colors and search_color_names. This provides clear guidance and alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns specific fields and focuses on active subscriptions. However, it does not mention the optional parameter's effect or pagination. Minor gap but overall adds good 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 sentences: first states purpose and return fields, second gives usage guidance. Front-loaded, no fluff, every sentence earns its place.

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

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

For a simple read-only list tool with one optional param and no output schema, the description covers purpose, usage, and return structure. Lacks mention of pagination or limits, but overall fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. But description says 'List the caller's active subscriptions' while parameter 'include_inactive' allows including cancelled ones. This inconsistency could mislead an agent into thinking only active are returned. Description does not clarify the optional parameter or its effect.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the returned fields (id, type, etc.). It also distinguishes from siblings by mentioning use cases like reviewing before adding more or finding an id to cancel.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This implies not to use when adding/removing subscriptions, with subscribe/unsubscribe as alternatives.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds further behavioral context: return values (closest name, canonical hex, RGB, perceptual distance), optional list parameter, and default behavior. No contradictions.

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

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

Four concise sentences, front-loaded with the core purpose, no redundant information. 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?

Despite no output schema, the description fully explains return values and behavior. With clear parameters and safety annotations, the tool is fully described for correct invocation.

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

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

Schema coverage is 100%, and the description adds significant value beyond schema: explains hex formatting (with/without #, comma-separated), gives list examples, and specifies default. Enriches parameter understanding.

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

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

The description clearly states the tool finds the nearest human-friendly color name for hex colors, distinguishing it from siblings like list_palettes or search_color_names. Specific verb 'Find' and resource 'color name' are explicit.

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

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

The description provides clear usage scenarios, formatting examples, and an alternative (list_palettes), but does not explicitly state when not to use this tool. Still strong 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 indicate non-read-only and non-destructive behavior, but the description adds crucial context: rate limits, free usage, no quota impact, and that feedback is reviewed daily, affecting the roadmap. This fully discloses what happens when the tool is used.

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-loading the main purpose and then adding necessary detail. Every sentence provides unique value, and there is 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 tool's simple purpose (sending feedback) and the rich input schema, the description covers all necessary aspects: types, context usage, message format, rate limits, and behavioral expectations. 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 value beyond the schema by explaining the enum options explicitly, advising on message length (1-2 sentences, 2000 char limit), and providing a concrete example of how to structure feedback. This helps with accurate parameter filling.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team. It explicitly lists feedback types (bug, feature, data_gap, praise) and when each is appropriate. This distinguishes it from sibling tools, which are query/information tools.

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

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

The description provides explicit guidance on when to use each feedback type, including a negative guideline to avoid pasting end-user prompts. It also mentions rate limits (5 per day) and that the tool is free, helping the agent decide when to invoke 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 declare safe, read-only, idempotent behavior. The description adds valuable context: data is self-aggregating, no PII, and cached with specific freshness (5min-1h). 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, front-loaded with the core purpose, and uses numbered lists for clarity. 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 simple tool (one optional parameter, full annotations, no output schema), the description covers purpose, usage, behavioral details, and return data structure (top tools, top packs, total call volume, with pack/tool/count tuples). No gaps.

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

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

Schema coverage is 100% with a descriptive enum parameter. The description reinforces the parameter's meaning and links it to use cases, though it doesn't add new technical details beyond the schema description.

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

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

The description clearly states the tool returns trending data (top tools, top packs, call volume) from other AI agents' usage on Pipeworx. It distinguishes from sibling tools like 'discover_tools' by focusing on real-time popularity.

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

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

The description provides three explicit use cases and explains the trade-off of the window parameter (shorter for hot trends, longer for steady-state). It guides when to use this tool effectively.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description goes far beyond by detailing internal logic: monotonicity checks, partition_sum, Jaccard similarity filtering, placeholder filtering, and fill_check using CLOB depth. It even explains when not to trade (realizable_edge_pp ≤ 0). This provides exceptional behavioral transparency.

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

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

The description is densely packed with technical details (e.g., 'SEMANTIC ANCHOR', 'PARTITION FILTER') and is quite verbose. While it is well-structured with sections, it could be more concise by deferring some implementation details to documentation or output schema. It earns a 3 for being functional but not optimally concise.

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

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

Given the tool's complexity (multiple modes, edge cases, fill risk) and the absence of an output schema, the description thoroughly covers return values (opportunities[], partition_check fields), error signals (skipped_low_similarity, placeholders_filtered), and cross-references custom sizing. It leaves no major gaps for an AI agent to interpret.

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

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

Input schema covers 100% of parameters with descriptions. The description adds significant value by providing concrete examples ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal') and explaining how each parameter alters the tool's behavior and the types of arbitrage opportunities detected.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three distinct modes (trending_scan, event, topic) with different use cases, effectively distinguishing the tool from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each argument mode: 'Call with NO args for a trending_scan... pass event for strongest per-event... topic for cross-event.' It also references an alternative tool for custom sizing ('use polymarket_fill_risk'). However, it does not explicitly state when NOT to use this tool versus other sibling tools like polymarket_kalshi_spread.

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 extensive behavioral details far beyond annotations: caching policy (1h at KV level), response structure (by_segment, diagnostics), internal methodology for each segment (e.g., lognormal barrier, GDELT ratio, partition_overround with bias correction), and the 24h-move warning. This level of detail fully informs the agent about what the tool does internally and what to expect.

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

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

The description is thorough but overly long and dense, lacking clear structural breaks like headings or bullet points. While front-loaded with the main purpose, the technical details are presented in a single wall of text, which may be overwhelming for an agent to parse quickly. Conciseness could be improved without sacrificing essential information.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains the output structure (by_segment, diagnostics, Fed candidates), caching behavior, edge-case handling (placeholder-slug filter, Fed reliability note), and all three segments' methodology. There is no missing context that would leave an agent uncertain about what the tool returns or how it behaves.

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?

All 9 parameters have descriptions in the schema (100% coverage). The tool description further enriches parameter semantics with practical usage advice, such as explaining when to adjust slippage_pp, why min_kelly skips small opportunities, and how min_partition_leg_kelly applies specifically to partition arbs. This adds significant value 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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from siblings like polymarket_arbitrage by focusing on Pipeworx signals and providing a comprehensive overview of the three segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). The phrase 'Built for "what should I bet on today"' further clarifies its intended use.

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

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

The description provides clear context for when to use the tool (discovering opportunities with Pipeworx disagreement) and describes knobs for filtering based on tradeability. However, it does not explicitly exclude or compare against sibling tools like polymarket_arbitrage or polymarket_kalshi_spread, leaving the agent to infer differences. A brief note on when not to use this tool would strengthen the 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 provides extensive behavioral context beyond annotations: data source (daily snapshots), gaps due to cache-miss, TTL of 60 days, decay computation from daily closes, and detailed response structure. This aligns with annotations (readOnlyHint, idempotentHint) and adds valuable information about data freshness and limitations.

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

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

The description is well-structured with a clear opening statement, parameter details, and response format breakdown. It is informative but slightly verbose; could be tightened without losing clarity.

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

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

Given the absence of an output schema, the description thoroughly explains the response fields (tracked, expired, snapshot_dates) and their subfields. It covers edge cases (gaps, expiration) and limitations, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters described. The description adds default values (days=14, window=1wk) and clarifies the effect of parameters on response (e.g., snapshot_dates reflect days with data). This enriches the schema definitions without being redundant.

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: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question about how long an edge has existed and whether it's shrinking. This differentiates it from sibling tools like polymarket_edges, which likely provide raw edge data rather than temporal analysis.

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 context on when to use the tool (analyzing edge persistence and decay) and explains why a fresh wide edge differs from an old one. It also notes limitations (history depth bounded by 60-day TTL, decay from daily closes not intraday). However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds rich behavioral detail: 'walks the ladder', returns verdict (clean|degraded|cannot_fill), identifies 'thin_legs' and 'forced_directional_risk'. No contradictions; description significantly supplements 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?

Well-structured with bold section headers and bullet-like lists. Slightly verbose but each sentence adds necessary detail given the tool's complexity. Front-loaded with core purpose. Could trim some examples but overall appropriately sized.

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 comprehensively details all return fields for both modes, including edge cases ('thin_legs', 'forced_directional_risk'). Covers usage context, default values, and clamps. Complete for a pre-trade risk assessment tool.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning beyond schema: explains REQUIRES one of market or event, clarifies side defaults, and interprets size_usd differently for single-market ('max spend on buys, target proceeds on sells') vs basket ('settlement notional — shares per leg'). Adds 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?

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes single-market and basket modes with distinct return fields, and contrasts with siblings like polymarket_arbitrage and polymarket_edges by being a pre-trade risk check.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why (theoretical overround not capturable, partial fills cause directional risk), providing clear when-to-use guidance.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: it explains why spreads exist (different participant pools), details the compatibility_warning triggers (cross-type/subtype mismatches, semantic mismatch), and notes temporal alignment requirements. 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 verbose but well-structured with sections for modes, response, and safety fields. Every sentence adds value, but it could be slightly tightened. However, the density of information is high, and the structure aids readability.

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

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

Given no output schema, the description thoroughly explains the response structure (leg-by-leg prices, matched spread, safety fields) and complex concepts like compatibility_warning and temporal alignment. It covers edge cases and provides examples in the input schema. The description leaves little ambiguity for a complex tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds significant value: it explains the interplay between topic and explicit parameters (explicit overrides topic side), provides concrete example values, and clarifies that topic is a pre-mapped shortcut. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from other tools by focusing on this specific arbitrage signal, and the examples and modes leave no ambiguity.

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 explains two modes (topic shortcuts and explicit pairings) and when to use each. It provides detailed guidance on interpreting safety fields (compatibility_warning, temporal_alignment), including when spreads are not tradeable. It also warns that pre-mapped topics often return compatibility warnings, managing expectations.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds scoping and relationship info, enhancing transparency without contradiction.

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

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

Two concise, well-structured sentences with front-loaded purpose, no wasted words.

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

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

Given simplicity (1 optional param, no output schema), the description fully covers purpose, usage, behavior, and sibling relationships.

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 description for the only parameter 'key'. Description reiterates the same info, adding no deeper semantics beyond schema.

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

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

The description clearly states it retrieves a saved value or lists all keys (verb+resource), and distinguishes from siblings like remember and forget.

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

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

Explicitly states when to use (look up stored context) and mentions scoping, but doesn't 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, idempotentHint, and destructiveHint. The description adds context about the mark_read option (which can change read state) and that polling is safe. There is a minor potential contradiction: idempotentHint=true may not hold for calls with mark_read=true, but the description does not address this.

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 concise (~5 sentences), front-loaded with purpose, and each sentence adds value. No redundant or excessive content.

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

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

Given 5 parameters, no output schema, and no nested objects, the description covers key use cases (filtering, mark_read, polling, alternative access) and mentions return fields. It is complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description mentions filtering by type and since as examples but does not add significant meaning beyond the schema descriptions.

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

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

The description specifies a clear verb ('Pull'), resource ('fired events from your subscription feed'), and key fields (source, citation_uri, payload). It differentiates from sibling tools like 'list_subscriptions' by focusing on events rather than subscription management.

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

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

Provides explicit guidance on filtering by type and since, using mark_read to manage read state, and notes that polling works fine. It also mentions an alternative access method (GET endpoint). However, it does not explicitly contrast with sibling tools for when to use this vs. alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and nondestructive. The description greatly enriches this by detailing the fan-out behavior across SEC EDGAR, GDELT→GNews fallback, and USPTO, including rate-limit fallback logic and the USPTO soft-fail condition. It also describes the return structure (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is a single, dense paragraph that front-loads purpose and usage queries, then efficiently covers sources, parameter formats, return structure, and cross-reference to sibling tool. Every sentence adds value; there is no filler or repetition.

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

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

The tool has no output schema, but the description summarizes the return structure (changes[], total_changes, citation URIs) and explains source behaviors and fallback logic. It mentions limitations (USPTO soft-fail) but does not specify pagination or maximum results, which would be useful for an agent. Still, for a multi-source aggregation tool, this is quite complete.

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

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

Schema description coverage is 100%, but the description adds value beyond the schema. For 'since' it expands on acceptable formats (ISO date or relative shorthand like '7d', '30d', '3m', '1y') and recommends a typical usage. For 'value' it explains ticker or CIK. The 'type' parameter is covered sufficiently. Given high schema coverage, the extra context raises the score above 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 opens with a list of natural language queries ('What's new with X') that map directly to the tool, then clearly states the verb and resource: 'change feed for a company in the last N days/weeks/months'. It explicitly distinguishes from the sibling tool 'entity_profile' by telling the agent to use that for static profiles.

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

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

The description explicitly tells the agent when to use this tool (for 'what's new' questions) and provides an alternative: 'Use entity_profile instead when you want the static profile…'. It also gives practical guidance on parameter usage (e.g., 'Use "30d" or "1m" for typical monitoring'). However, it does not exhaustively cover when NOT to use this tool relative to all 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?

Discloses key-value storage, scoping by identifier, and persistence details (authenticated vs anonymous). Adds value beyond annotations which only indicate idempotent and non-destructive. 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?

Front-loaded with purpose, then usage, then details. Every sentence provides unique information with no redundancy. 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?

Covers purpose, usage, persistence, scoping, and sibling tool pairing. Fully adequate for a simple store operation with no output schema.

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

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

Schema coverage is 100%, but the description adds examples for key ('subject_property', 'target_ticker') and clarifies value as 'any text — findings, addresses, preferences, notes', enhancing meaning.

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

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

The description clearly states the verb 'Save' and resource 'data', with specific scope 'across this conversation or across sessions'. It distinguishes from sibling tools by mentioning 'recall' and 'forget'.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and directs to pair with 'recall' and 'forget'. Provides clear context and alternatives.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals that the tool cascades through several internal lookup endpoints, replacing 2-3 manual lookups. This adds useful behavioral context without contradicting annotations.

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

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

The description is moderately long but well-structured: starts with query examples, then states purpose, then details supported types. Every sentence adds value; minor trimming possible but not necessary.

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 the return values (ticker, CIK, RxCUI, etc.) and the disambiguation behavior. It is complete given the tool's complexity and the richness of annotations.

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

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

Schema coverage is 100%, and the description adds substantial meaning: it provides example values for each parameter, explains what each entity type returns (e.g., ticker+CIK for company), and notes auto-disambiguation. This goes well 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 resolves user-spoken names to canonical identifiers for company or drug entities. It uses specific verbs and provides examples, and distinguishes it from siblings by positioning it as the first tool to use when a name is given but an ID is needed.

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 says 'Use FIRST whenever you have a name but need an ID,' giving clear usage context. It does not explicitly list alternatives or exclusions, but the context is strong enough for an agent to decide when to invoke this tool.

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

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

The annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) already indicate safety and idempotency. The description adds that the tool probes each entity with 'ai_visibility_check', ranks by score, and returns a ranked list with fields (score, confidence, signal density). This behavioral detail is beyond what annotations provide, but lacks specifics on rate limits or failure modes.

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, zero wasted words. The first sentence clearly states the purpose. Subsequent sentences add usage context and return details. Well-structured and front-loaded.

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

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

For a tool with 4 parameters, one required, and no output schema, the description covers the essential aspects: what it does, how it works internally (calls ai_visibility_check), what the output provides (ranked list with metrics). It is sufficient for an agent to understand the tool's functionality and expected results.

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

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

Schema description coverage is 100% so the schema already documents all parameters. The description adds value by explaining the role of 'entities': the first is the 'subject' and the rest are competitors. This contextual meaning is not in the schema and helps the agent use the tool correctly.

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 'Compare' and identifies the resource as 'AI visibility across multiple entities side-by-side'. It clearly distinguishes from sibling tools like 'ai_visibility_check' which checks single entities, and 'compare_entities' which is more general. The purpose is 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 explicitly states the use case: 'competitive AI-marketing audits' with an example question. It implies when to use this tool over alternatives. However, it does not explicitly state when not to use or mention alternative tools by name, though the sibling list provides context. Still clear enough for selection.

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 important behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeouts. Annotations already indicate readOnly, idempotent, and non-destructive, and description adds operational context.

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

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

Well-structured: front-loaded with core purpose, then details data sources, return contents, ecosystem scope, and failure behavior. 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 no output schema, the description fully covers return fields (summary block, advisories, links, alternative versions), ecosystem limitation, and graceful failure. It provides complete context for an agent to invoke and interpret results.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant new meaning beyond the schema; it mentions package name and version default but duplicates schema info. Minimal added value.

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

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

The description clearly states the tool's purpose as a composite check for adding an npm package, covering safety, popularity, and size. It uses specific verbs ('scan', 'fans out') and identifies the resource (npm packages). It distinguishes from siblings by noting NPM ecosystem only and referencing deps.dev:version for other ecosystems.

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

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

Explicitly tells when to use: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also specifies when not to use (other ecosystems) and directs to deps.dev:version for those, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds return value details (hex codes) and list option, but does not elaborate further on behavioral traits 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?

Two efficient sentences. The first introduces the core function with examples, and the second adds return values and optional parameter, with no wasted words.

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

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

For a simple search tool with 2 parameters, good annotations, and no output schema, the description covers all necessary context: input, output, and optional restriction. 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%, so baseline is 3. The description adds concrete examples for `name` and cross-references `list_palettes` for `list`, providing context beyond the schema.

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

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

The description clearly states it searches color names by substring, returns matching names with hex codes, and optionally restricts to a named list. It uses specific examples and distinguishes from sibling tools like list_palettes.

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 (substring search) and mentions the optional list parameter with a reference to list_palettes for available lists. It lacks explicit when-not-to-use, but the guidance is clear.

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

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

Describes embedding model (BGE-base-en), window size (500-char overlapping), char limit (200K) with truncation and flagging, and that passages carry offsets. Goes well 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?

Front-loaded with core purpose, then logically flows to usage, pairing, and technical details. Every sentence adds value with no fluff.

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

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

Despite no output schema, describes return format (passages with offsets and scores), parameter constraints, and pairing context. Complete for a 3-param 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%, so baseline is 3. Description adds value with truncation details, example queries, and limit defaults, justifying a 4.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb, resource, and output (passages with offsets and scores). It 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 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, providing clear when-to-use and alternative.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds significant behavioral context: auth requirements, return of subscription ID, delivery details, webhook signing secret, auto-disable after 10 consecutive failures. 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?

Description is information-dense but well-structured, starting with purpose and then detailing types and delivery. It could benefit from bullet points or clearer separation, but every sentence adds value. Slightly long 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?

Tool is complex with 3 parameters (one enum, nested objects) and no output schema. Description covers all necessary aspects: auth prerequisites, type-specific params, delivery options with limits, and return of subscription ID. Sibling tools are present (unsubscribe, list_subscriptions), providing complete context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds substantial meaning beyond schema: detailed examples for each type (e.g., 'sec_8k: items:["5.02"] = officer change'), delivery constraints (SMS verification, webhook signing), and required fields for clinical_trial. This is beyond what the schema provides.

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

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

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with specific verb and resource. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation, and mentions the return of a subscription ID.

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 extensive when-to-use guidance: requires Pipeworx OAuth account, lists supported types with examples, and details delivery channels with limitations (e.g., SMS 10/day cap). It indirectly suggests when not to use (e.g., anonymous users cannot persist subscriptions), but could explicitly contrast with alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it is onboarding-focused and returns example questions with tool shapes, but does not contradict annotations. It provides useful behavioral context beyond the annotations.

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

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

The description is well-structured, starting with common query examples, then stating purpose, listing topics, and giving usage advice. It is slightly verbose with the topic enumeration but each part adds value. It earns its length.

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

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

Given the simple input schema (1 optional param) and no output schema, the description fully explains what the tool does, when to use it, argument behavior, and the nature of return values. It covers all necessary context.

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

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

Schema coverage is 100%, baseline 3. The description goes beyond by providing examples of topic values ('finance', 'pharma', etc.), explaining the effect of omission vs. passing a topic, and adding context about the nature of the output. This significantly enriches parameter understanding.

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

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

The description clearly states the tool returns category-bucketed example questions for Pipeworx, with specific verbs like 'returns' and 'the onboarding entry point'. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its role as a first-use guide.

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

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

The description explicitly tells when to use the tool: 'FIRST when you do not yet know what Pipeworx can do for you', and how to call it with or without the topic argument. It also hints at alternative meta-tools, providing clear usage direction.

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

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

The description adds behavioral context beyond annotations: ownership enforcement and deactivation with historical availability. Annotations already indicate non-destructive and idempotent, so the description adds moderate 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 two sentences, front-loaded with the action, and each sentence adds critical information without waste. Highly concise and well-structured.

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

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

For a simple tool with one parameter, good annotations, and no output schema, the description covers the essential aspects: action, ownership, side effects, and link to related tool (recent_alerts). Complete enough for correct 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% and the description references 'by id', but does not add significant meaning beyond the schema's parameter description. 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 'Cancel a subscription by id' with a specific verb and resource, and distinguishes from siblings like subscribe, list_subscriptions, and recent_alerts by mentioning ownership enforcement and deactivation 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?

The description provides useful context on when to use (cancel own subscriptions) and the effect (deactivation not deletion, history preserved via recent_alerts), though it does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., so the safety profile is clear. The description adds significant behavioral context: it returns a verdict (with exact options like 'confirmed', 'refuted'), extracted structured form, actual value with a pipeworx:// citation, and percent delta. It also explains the tool replaces multiple sequential calls, highlighting efficiency. 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 informative but moderately long. It starts with trigger phrases for easy identification, then states use case, domain, and output format. While every sentence adds value, the list of trigger phrases could be slightly trimmed. Overall efficient and well-structured.

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

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

Given the tool's simplicity (single parameter, no output schema), the description is sufficiently complete: it covers purpose, trigger phrases, domain, output structure, and efficiency gains. However, it lacks mention of error handling or limitations for non-financial claims, which would enhance completeness.

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 'claim' parameter. The tool description does not add additional parameter-level detail beyond the schema's description. However, the schema's parameter description is already thorough, so the tool description adds marginal value. 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 the tool's purpose: natural-language claim verification against authoritative sources. It specifies the verb (validate/verify), resource (claim), and scope (company-financial via SEC EDGAR + XBRL). It also distinguishes itself by noting it replaces 4-6 sequential calls, making its consolidation role clear.

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 trigger phrases ('Is it true that…', 'fact check') and states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the domain (company-financial claims for public US companies). However, it does not mention when not to use it or alternative tools among siblings, missing some guidance on exclusion.

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