Amplitude

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

Adds significant detail beyond annotations: scores 0-100, per-model return structure, cost implications for Anthropic, default model. 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?

Short, front-loaded sentences. Every sentence adds value. Clear structure: action, default, optional, return, use 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?

Given 4 parameters and no output schema, description fully explains behavior, return format, and usage. Complete for agent to invoke correctly.

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

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

Schema coverage is 100% but description adds meaning: explains default model, apiKey usage, context purpose. Enhances understanding beyond schema.

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

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

Clearly states the verb 'probe' and 'score', and resource 'LLMs' for visibility. Distinguishes from siblings by focusing on AI visibility scoring for entities.

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

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

Describes default model and optional Anthropic usage with key. Explicitly mentions use cases like AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly contrast with alternatives but context sufficient.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds that it 'Returns totals and trend data,' which is useful but does not disclose additional behavioral traits such as rate limits or data freshness.

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

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

Two sentences front-loaded with the verb and resource. Concise with no wasted words. However, the granularity phrasing could be more precise to avoid confusion.

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

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

Given the presence of a rich annotation set and an output schema, the description covers the tool's purpose and key features (totals, trend data, granularity). It is adequate for a simple data retrieval tool, though minor inaccuracies around granularity exist.

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 mentions 'granularity (daily, weekly, or monthly),' which is not reflected in the schema (the 'm' parameter is for metric, not granularity). This adds context but potentially introduces inconsistency.

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

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

The description clearly identifies the verb 'Get', resource 'active user counts', and specifies the returned data (totals and trend data). It distinguishes from sibling tools like amp_get_events or amp_get_retention by focusing on active user counts.

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

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

The description mentions granularity options (daily, weekly, monthly) and date range, which implies usage context, but lacks explicit guidance on when to use this tool versus alternatives like amp_get_events. No when-not or exclusion criteria are stated.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is covered. The description adds behavioral context (returns frequency, segments, trends) but does not go beyond what annotations already imply. No contradiction.

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

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

Two sentences, front-loaded with purpose and examples. Every sentence adds value without redundancy. Appropriate length for the tool's 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?

Output schema exists, so return values are covered. The description explains what is returned (frequency, user segments, trends) and date range. Minor gap: no mention of data freshness or latency, but overall complete for a read-only analytics 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 parameters are already well-documented. The description adds minimal extra semantic value beyond repeating date range format and event name. Examples in schema provide context, but description itself doesn't enhance beyond baseline.

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

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

The description clearly states it gets event counts and breakdowns for a date range, specifying return types (frequency, user segments, trends). This distinguishes it from sibling tools like amp_get_active_users or amp_get_retention, which focus on different analytics.

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: to retrieve event metrics over a date range, with example dates. However, it does not explicitly exclude cases or mention alternative tools, leaving some guidance gap for agents.

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

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

Annotations already provide readOnlyHint and idempotentHint, so the description adds value by specifying the output format (retention percentages by time period). This goes beyond the annotations while staying consistent with them.

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

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

The description is concise with two sentences: the first states the core purpose, the second clarifies the return format. No extraneous information, every word 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 existence of an output schema and full parameter documentation, the description is complete enough. It explains the return value (retention percentages) but could optionally mention the cohort definition or default period granularity.

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 adequately documents all 5 parameters. The description does not add any additional parameter-level details beyond what is in the schema, meeting the baseline expectation.

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

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

The description uses a specific verb ('Get') and resource ('user retention metrics') and clearly states what is returned (retention percentages by time period). The tool's purpose is distinct from siblings like amp_get_active_users or amp_get_events, which focus on different metrics.

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

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

The description implies usage for analyzing cohort retention over time but does not explicitly state when to use this tool versus alternatives (e.g., amp_get_active_users). No when-not or alternative tools are mentioned, leaving the context of use somewhat vague.

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, so the description's addition of 'returns events with timestamps, properties, and interactions' adds some value by hinting at the output structure. However, it does not disclose pagination behavior, authentication requirements, or the fact that it uses an internal user ID from amp_user_search.

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

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

The description is a single sentence that concisely conveys the tool's purpose and output. It is front-loaded with the action and subject. However, it could be slightly more structured, e.g., by explicitly listing the returned fields.

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

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

Given the existence of an output schema (not shown but present) and full parameter documentation, the description is fairly complete. It explains the core functionality and what is returned, though it does not mention pagination or the need for an amplitude_id from a previous search.

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

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

The input schema has 100% description coverage for all 5 parameters, including limit, offset, API keys, and amplitude_id. The description only adds 'for a specific user,' which is already implied by the amplitude_id parameter. Thus, the description adds minimal semantic value beyond the schema.

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

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

The description clearly states the tool retrieves a recent event activity timeline for a specific user, with timestamps, properties, and interactions. This verb-resource combination is specific and distinguishes it from sibling tools like amp_get_events (which may be broader) or amp_get_active_users (focused on active users).

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 no guidance on when to use this tool versus alternatives, such as amp_get_events or amp_user_search. It does not mention prerequisites, limitations, or when to avoid using it. The agent must infer usage from the tool name and context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by specifying what is returned (matching profiles with properties, event history, and segments), which goes beyond annotations. 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?

Single sentence that is clear and to the point. No wasted words; front-loaded with the primary action and succinctly describes what the tool returns.

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 has 3 required parameters, full schema coverage, an output schema (present but not shown), and rich annotations, the description provides sufficient context. It explains the search input and the output content, making the tool well-understood.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by providing examples of search terms (e.g., email, user_id) and clarifying the 'user' parameter's allowed values. This enhances understanding beyond the schema alone.

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

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

Description clearly states the tool searches for users by ID or property (e.g., email, user_id) and returns profiles with properties, event history, and segments. This is a specific verb+resource combination that distinguishes it from sibling tools like amp_get_active_users or amp_get_events.

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

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

Description implies usage for user search but does not provide explicit guidance on when to use this tool vs alternatives like amp_get_user_activity. No exclusions or alternative recommendations are given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable behavioral detail: the tool routes to one of 5,564 tools across 1462 sources and returns structured answers with stable citation URIs. This goes beyond what annotations provide, though it does not detail rate limits or latency, so a 4 is appropriate.

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

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

The description is comprehensive but somewhat verbose, with multiple clauses and a long list of examples. It could be trimmed to front-load the main purpose and usage guidelines. While every sentence adds value, the length reduces conciseness, so a 3 is fair.

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 broad scope (routing to thousands of tools), the description covers its purpose, usage, alternatives, and return format (structured answer with citation URIs). There is no output schema, but the description explains what the agent will get. Slightly lower because it doesn't mention error handling or when the tool might fail (e.g., ambiguous questions), so a 4.

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

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

The input schema covers all parameters with descriptions, so schema_description_coverage is 100%. The description does not add new parameter-specific meaning beyond reiterating that the question is in natural language, which matches the schema. Baseline 3 is correct as the description adds no extra semantic value for parameters.

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

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

The description clearly states a specific verb-resource pair ('routes the question to the right tool') and distinguishes it from siblings by listing detailed use cases (SEC filings, FDA data, etc.). It explicitly contrasts with ask_pipeworx_grounded and deep_research, making the tool's purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool ('PREFER OVER WEB SEARCH'), when to step up (ask_pipeworx_grounded for verbatim evidence, deep_research for multi-part questions), and gives concrete example queries. It also tells the agent to start here as a default entry point, which is a strong usage guideline.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals it is a full working router (not a fallback), that it may have candidate routing improvements when active, and that its behavior is currently identical to ask_pipeworx. 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 compact—just a few sentences—with no filler. It front-loads the key identity ('Beta version of ask_pipeworx') and efficiently conveys purpose, usage, and current state.

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

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

The description covers the tool's relationship to the stable version, its experimental nature, current status, and instructions for use. It does not detail return values, but the context signals show no output schema and the description mentions 'same response shape' as ask_pipeworx, which is sufficient for decision-making.

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

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

Schema coverage is 100% with clear descriptions for the single required 'question' parameter and its aliases. The description does not add parameter-level detail beyond what the schema provides. Baseline 3 is appropriate given full schema coverage.

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 this is a beta version of ask_pipeworx, an identical universal router with the same tools and arguments, but with candidate routing improvements. It distinguishes itself from the stable sibling by emphasizing the experimental edge and current equality.

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

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

The description explicitly says to use it like ask_pipeworx when wanting the newest routing, and notes results are compared to the stable router for merge decisions. It also clarifies that no candidate is currently active, making it identical for now, which aids in tool 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?

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safe read-only behavior. The description adds transparency by detailing the refusal reasons (not_in_source, no_tool_match, etc.) and the extra cost, which are beyond annotations. However, it doesn't explicitly mention that the tool is idempotent (consistent with annotation) or the implications of open-world hint, but these are minor gaps.

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

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

The description is well-structured and front-loaded with the core purpose. It efficiently conveys the behavior, refusal mode, and use cases in just a few sentences without redundancy. 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?

Despite lacking an output schema, the description compensates by fully specifying the return format, including success fields (answer, evidence, confidence, source, fetched_at) and refusal reasons. The tool is complex (high parameter count, many siblings), but the description provides enough context for selection and invocation without needing additional documentation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that the question parameter accepts multiple aliases (query, q, prompt, text, input), which is not fully detailed in the schema's individual parameter descriptions. It also explains the nature of the question (natural language for lookup), though this is somewhat implied by the tool's purpose. This raises the score to 4.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads. It specifies that it extracts answers using only tool results, distinguishes itself from ask_pipeworx, and lists concrete use cases like financial verdicts, legal claims, and medical 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 tells when to use this tool (high-stakes reads where answers will be quoted or cited) and when to prefer ask_pipeworx (casual lookups), along with the cost trade-off of an extra LLM call. It also describes the refusal behavior, making it clear when the tool should not be used.

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. The description goes far beyond: explains resolver confidence scoring, parent_event extraction, news field fallback, safety low-confidence blocking, closed market handling, wide-spread warning, and cancellation-rule risk. 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 very long, single paragraph with no section breaks or bullet points. While informative, it is not concise and could overwhelm the agent. Every sentence is valuable, but structure is poor.

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 documents return fields: result.market (bid/ask/spread), result.analysis (model_probability/edge_pp/kelly), result.evidence (keyed by source), plus edge cases (low_confidence_match, market_closed_or_inactive, illiquid_wide_spread, cancellation_rule). It covers all aspects an agent needs.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains that 'market' accepts slug, URL, or text; defines 'depth' (quick vs thorough) and 'include_raw' (summarized vs full payloads). These clarify usage 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?

First sentence clearly states 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Use cases are explicitly given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This distinguishes from sibling tools like polymarket_edges 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 clear context for when to use the tool ('Use for...'), but does not explicitly exclude cases or compare to alternatives. However, the context is sufficient 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 declare readOnlyHint=true and non-destructive. The description adds valuable behavioral details: data sources per type (SEC EDGAR/XBRL for companies, FAERS/FDA/trials for drugs), sorting by primary metric, return of paired data and citation URIs, and correct handling of off-calendar fiscal years. No contradictions with annotations.

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

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

The description is a single dense paragraph but packs essential information efficiently. It front-loads common query patterns, then defines the action, data sources, and return format. Every sentence adds value. Could be slightly more structured with line breaks for readability, but it's concise 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?

Given no output schema, the description fully explains return contents (paired data + URIs), covers both entity types, mentions sorting, and highlights the efficiency benefit (replaces 8-15 lookups). It addresses constraints (2-5 items) and data source specifics. This is complete for a 2-parameter tool with clear 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. The description adds concrete examples for each parameter (e.g., tickers for company, drug names for 'values'), explains the enum effect for 'type', and clarifies min/max constraints. This goes beyond the schema's own descriptions, adding practical context for agents.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs. It includes a variety of query patterns ('compare X and Y', 'X vs Y', etc.) and distinguishes itself from sequential lookups by explicitly noting it should be preferred over multiple single-profile calls. The purpose is specific and unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use this tool. It also gives example queries. However, it does not explicitly state when not to use it (e.g., for detailed single-entity profiles, which sibling 'entity_profile' would handle), but the guidance is strong and contextually sufficient.

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

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

Annotations already declare readOnlyHint=true (but description adds value beyond annotations). The description explains the internal decomposition and parallel routing, expected latency (15-90s), the meaning of gaps[] and contradictions[], the citability guarantee (citation_uri only when fetchable), and the semantic excerpting behavior. This goes far beyond what annotations provide.

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

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

The description is comprehensive but somewhat long. It front-loads critical info (account, tier restrictions) and ends with latency. Every sentence adds value, but the length might deter a quick skim. A tighter structure with bullet points could improve scannability while preserving 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 (2 params, no output schema, many sibling tools), the description covers: purpose, usage context, behavioral details (decomposition, parallelism, gaps, contradictions, citation resolution, semantic excerpting), required auth/account, latency, and when to prefer siblings. No output schema exists, but the description details the return format sufficiently.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value: it explains the depth parameter's three levels with concrete behavior (gap recovery, contradiction scan, lead chasing) and the question parameter's intended usage (broad/multi-part is fine). The only reason not a 5 is that the description doesn't add format constraints not already in the schema.

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

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

The description clearly states the tool performs grounded multi-source research across structured data sources, not open-web search. It specifies the verb 'research', the resource 'Pipeworx's structured data sources', and the scale (one call vs many tools). It distinguishes itself from siblings like ask_pipeworx (single lookup) and bet_research, validate_claim, etc., by clarifying it decomposes multi-part questions.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to use (breaking news, colloquial current-news, single lookups). Names alternatives: ask_pipeworx for single lookups or live news APIs, and notes that deep_research returns empty gaps for non-structured topics. Also mentions account requirements and depth tier eligibility.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's additional detail about returning ready-to-call results with full schemas adds value. No contradictions found.

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

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

The description is well-structured and front-loaded, but slightly verbose with extensive domain listing. Every sentence contributes meaning, though some redundancy exists (e.g., mentioning aliases both in schema and description).

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

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

Despite no output schema, the description thoroughly explains what is returned: top-N tools with names, descriptions, and full input schemas ready to call. The input is well-covered, and the tool's complexity is low, so 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%, with each parameter documented. The description adds curated examples and explains the result format, but the schema already covers aliases and types. Baseline of 3 is appropriate given high coverage.

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 with a specific verb ('Find') and resource ('tools by describing the data or task'). It lists many example domains (SEC filings, FDA drugs, etc.) and distinguishes itself from sibling tools by being the one for discovering what exists.

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

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

The description explicitly advises to call this FIRST when exploring many tools, providing clear context for use. It does not explicitly state when not to use it or name alternatives like search_within, but the guidance is strong enough that an agent would understand when to invoke this over specific tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral context: fans out across multiple sources, returns specific fields, notes patent API sunset, and mentions fallback mechanisms. Does not disclose potential rate limits or latency but 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?

Dense but well-organized description starts with examples and usage priority, then details output and notes. Every sentence adds value, though slightly longer than minimal. Structure is logical and easy to parse.

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

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

Given the complexity (multiple sources, fallbacks, specific fields) and no output schema, the description is quite complete. Lists return fields and their sources, but does not specify exact JSON structure or pagination. Adequate for an agent to understand the tool's capabilities.

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

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

Input schema has 100% description coverage. Description adds meaning: type is only 'company', value must be ticker or zero-padded CIK, and explains why names are unsupported. This enriches 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 uses specific verbs ('profile', 'research', 'brief on') and clearly states the tool produces a full cross-source profile of a US public company, listing data sources and return fields. It immediately distinguishes from siblings like resolve_entity by specifying input requirements.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and warns that names are not supported, directing to use resolve_entity first. Provides clear when-to-use and when-not-to-use guidance.

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

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

Description adds behavioral context (e.g., clearing sensitive data) beyond the annotations. Both destructive and idempotent hints are matched, 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?

Extremely concise: two sentences that front-load the action and purpose, 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?

Complete for a simple tool: explains purpose, usage guidance, and pairing with siblings. No missing elements.

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

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

Schema coverage is 100% and the description does not significantly add beyond what the schema provides for the single parameter.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource, and distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use ('context is stale, task is done, clear sensitive data') and pairs with alternatives, providing clear guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that it fetches a page and extracts content, but does not disclose potential errors, timeouts, or limitations (e.g., only works for HTML pages).

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 well-structured sentences with no extraneous text. The first sentence states purpose, the second adds process detail, the third specifies output format, and the fourth lists usage scenarios.

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?

Annotations and schema cover safety and parameters adequately. The description adds usage context and output format. However, missing guidance on URL accessibility requirements or error handling, which would make it fully 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 the description does not need to add param details. It implicitly mentions 'max_links' via 'key links' but does not clarify its behavior 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 'Generate a production-ready llms.txt file for any URL' with a specific verb and resource, and distinguishes it by naming the output format and use cases.

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

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

Provides use case examples ('getting a client's site indexed', 'drafting for your own project', 'auditing competitor') but does not explicitly differentiate from sibling tools like ai_visibility_check or scan_competitor_ai_presence, nor state when not to use it.

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

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

Annotations already declare readOnly, idempotent, not destructive. The description adds that only active subscriptions are returned by default and optionally inactive, providing 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?

Two succinct sentences: first defines purpose and output, second gives usage guidance. No redundant words or fluff.

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

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

Given no output schema, the description details return fields. Annotations cover safety. Sibling context is addressed. Lacks mention of pagination or limits, but for a simple list tool this is minor.

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

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

Schema covers the single optional parameter fully (100% coverage). Description mentions 'active' which aligns with the default, but adds no new details about the parameter. 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 lists the caller's active subscriptions and specifies the return fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe and unsubscribe by focusing on reading rather than modifying.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for usage relative to subscribe/unsubscribe siblings.

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

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

Annotations set readOnlyHint=false, but the description adds substantial behavioral context: rate limiting ('Rate-limited to 5 per identifier per day'), no quota impact, and the claim_token return mechanism. It also tells users not to paste end-user prompts and explains that feedback directly affects roadmap—information not inferable from the annotations alone.

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?

Although long, every sentence earns its place: it covers scope, categories, exclusions, token workflow, rate limits, and incentives. The opening sentence front-loads the core purpose, and there is no redundant restatement of the schema.

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 adequately covers return behavior by mentioning the claim_token and how to use it later. It also covers scope restrictions, rate limiting, and content guidelines, making the tool fully usable without additional documentation.

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

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

Schema coverage is 100% and enum descriptions are already detailed, so the baseline is 3. The description adds meaning by explaining claim_token semantics ('pass the pwfb_… token that filing returned, with no other arguments') and by instructing users to 'describe the issue in terms of Pipeworx tools/packs' rather than pasting prompts. This is a meaningful addition beyond the schema.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist' and enumerates specific feedback types (bug, feature, data_gap, praise). It also explicitly scopes the tool to 'tools served by this Pipeworx connection,' distinguishing it from sibling tools and from tools belonging to other MCP servers.

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

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

Provides explicit when-to-use triggers: wrong/stale data for bugs, missing tools for features/data gaps, and praise for positive outcomes. It gives a clear exclusion: if the tool is from a different MCP server, 'we cannot fix it and reporting it here only delays you; file it with that server instead.' It even explains the follow-up workflow with claim_token.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds useful behavioral details: derived from CF analytics-engine, no PII, caching policy (5min-1h). This goes beyond annotations without contradicting them.

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

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

Description is front-loaded with the main purpose, followed by bullet-point use cases and additional details. While slightly verbose, every sentence adds value and it is 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?

Even without an output schema, the description explains what is returned (top tools, packs, total call volume) and the data format. It also mentions caching and data source, making the tool fully understandable for selection and invocation.

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

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

Schema coverage is 100% with a well-described enum. The description adds semantic guidance: shorter windows surface hot trends, longer windows show steady-state demand. This adds value beyond the schema's description.

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

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

The description clearly states it returns trending tools, packs, and call volume over specified windows. It provides specific use cases, making the purpose unambiguous and distinct from siblings like discover_tools or suggest_questions.

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

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

The description explicitly lists three usage scenarios, giving clear context for when to use this tool. It does not explicitly state when not to use it or name alternatives, but the guidance is strong enough for most agents.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral detail: scanning scope, partition checks, similarity filtering, placeholder exclusion, fill check against live order books. 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 thorough but not overly verbose. It is well-structured: summary, mode details, semantic anchor, partition filter, response, fill check. Each sentence contributes. Could be slightly tighter, but overall efficient.

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

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

Given the complexity and lack of output schema, the description is comprehensive. It covers algorithm details, edge cases (e.g., low similarity, placeholder filtering), and response structure. Minor omissions might exist, but sufficient for agent understanding.

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

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

Schema description coverage is 100% (both parameters have descriptions). The description adds context beyond the schema: explains event slugs vs. URLs, seed questions for topics, and internal behavior of each mode. This adds value, so 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 the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) and differentiates from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Explicit guidance is given: when to use no args, event, or topic, with recommendations (e.g., 'event recommended for a specific market'). It includes when not to trade (realizable_edge_pp ≤ 0) and references an alternative tool for custom sizing (polymarket_fill_risk).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds context: cache behavior (cached 1h at KV level), model families, tradeable-edge knobs, and diagnostic output. 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 very long and dense, including model formulas that may be extraneous. However, it is structured with segments and explanations. Given the complexity, it is organized but could be more concise.

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

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

No output schema, but the description details the response structure: by_segment{...}, fed_candidates/fed_note, and _diagnostics. It explains each segment and fields within opportunities, providing comprehensive 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%. The description adds significant meaning beyond the schema, e.g., explaining min_liquidity and max_spread_pp as 'Tradeable-edge filters' and detailing min_partition_leg_kelly's behavior with partition arbs. Baseline 3, extra semantics push to 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 that the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on edge detection via model-driven and structural arbitrage signals.

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

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

The description is built for 'what should I bet on today' and mentions agents discover opportunities without paging hundreds of markets. It also notes that Fed candidates are excluded from ranking. However, it does not explicitly state when not to use this tool or provide direct 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), the description explains data source (daily snapshots), output structure (tracked/expired/snapshot_dates), and limitations (60-day TTL, daily closes). 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 front-loaded with purpose and is comprehensive, though the RESPONSE block is lengthy. Every sentence serves a purpose, but could be slightly tightened.

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 three output arrays and their fields, plus notes on limits and data gaps, providing complete context for callers.

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 schema already describes parameters well. Description adds minor context (e.g., 'snapshot family') but does not significantly extend meaning beyond schema.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge longevity, distinguishing it from sibling polymarket_edges which gives raw snapshots.

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

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

The description implicitly guides when to use by framing the question it answers, but does not explicitly state when not to use or list alternatives.

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

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

Annotations indicate readOnly, idempotent, openWorld, non-destructive. Description adds behavioral detail: walks the order book ladder, returns top_of_book, VWAP fill price, slippage, shares filled, verdicts (clean/degraded/cannot_fill). Warns about risks like thin legs and forced directional risk. No contradiction with annotations.

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

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

Description is long but well-structured with clear mode breakdowns (single-market vs basket). Every sentence provides essential information. Could be slightly tightened, but the complexity of the tool justifies the length.

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

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

No output schema, but description fully documents return values for both modes including edge cases (thin_legs, forced_directional_risk). Covers default behavior, constraints (size_usd clamp 10–1,000,000), and provides actionable verdicts. Complete for an evaluation 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 covers all 4 parameters with descriptions. The description adds significant value: clarifies defaults (size_usd=1000, side default for basket auto), explains mutual exclusivity of market vs event, interprets size_usd differently for single-market vs basket, and describes side options in detail. Slightly wordy but adds meaning beyond schema.

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

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

Description clearly defines the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth. It distinguishes between two modes (single-market and basket/partition) and specifies what each returns. The sibling differentiation is explicit, telling the agent to use this before acting on polymarket_arbitrage signals or polymarket_edges trades above $500.

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

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

Provides explicit when-to-use guidance: before executing any polymarket_arbitrage sell/buy-every-leg signal or any polymarket_edges trade above $500. Explains why (theoretical overround on thin books is not capturable, partial fills convert arb to directional position). Clearly distinguishes from sibling tools.

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

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

Annotations report readOnlyHint, idempotentHint, and destructiveHint. The description adds extensive context: response format, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explains why some pairs are meaningless. No contradictions.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds value. However, it is slightly verbose; minor trimming could improve conciseness.

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

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

Given the tool's complexity (cross-venue spread, multiple modes, safety fields), the description thoroughly covers inputs, modes, output fields, and warnings. Even without an output schema, it explains response structure adequately 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% with each parameter described. The description enhances this by listing all topic shortcuts and providing explicit ticker/slug examples. It explains parameter interaction (topic overrides), adding value beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit custom pairing) and explains output, making purpose and scope unambiguous.

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

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

The description explains when to use each mode (topic for pre-mapped macro events, explicit for custom events) and warns that most shortcuts yield compatibility warnings. However, it does not differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, which is a minor gap.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context about scoping and the dual behavior (retrieve vs. list), which is helpful but not a major gap given 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?

Three sentences, no wasted words. The first sentence covers core functionality, the second adds examples, the third covers scoping and pairing. Very efficient, though the third sentence could be more concise.

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

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

For a simple tool with one optional param, no output schema, and comprehensive annotations, the description covers behavior (retrieve/list), usage examples, scoping, and pairing. It is fully sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with a single optional 'key' parameter described. The description clarifies that omitting the key lists all keys, but this is already implied by the required: [] and examples. No additional 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 the tool retrieves a value saved via remember or lists all saved keys. It distinguishes from siblings 'remember' and 'forget' by name, and uses specific verbs ('retrieve', 'list') and resources ('value', 'keys').

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

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

The description explicitly says when to use ('look up context the agent stored earlier') and mentions alternatives ('Pair with remember to save, forget to delete'). It also explains scoping to the user's identifier.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that mark_read modifies read state and feed is persisted, which is useful behavioral context beyond annotations.

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

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

Three sentences covering purpose, filters, and alternative access are efficient. Slightly verbose with 'the evaluator' phrasing but no waste.

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

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

Despite no output schema, description details return fields. Covers all key aspects: purpose, filters, side effects (mark_read), alternative access. Sufficient for correct tool selection and 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% but description adds examples (e.g., 'sec_8k' for type) and explains effect of mark_read on subsequent calls. This adds meaningful context beyond schema descriptions.

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

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

Description clearly states 'Pull fired events from your subscription feed' and details return fields (source, citation_uri, raw payload). Provides specific examples of filters (e.g., 'sec_8k') and usage patterns.

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 mentions 'Polls work fine' and provides alternative endpoint for scripts/dashboards. Implies use cases for mark_read and unread_only but lacks explicit differentiation from sibling tools.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavior: fan-out to multiple sources, fallback logic, sunset note, and return structure. No contradiction with annotations.

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

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

The description is somewhat lengthy but efficiently packed with information. It front-loads with examples and then details. Every sentence contributes, though density might be slightly high for quick scanning.

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

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

Despite no output schema, the description explains the return structure (changes grouped by source, total_changes, citation URIs). It covers data sources, fallback, and limitations (USPTO sunset). Distinguishes from sibling 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 3. The description adds meaning: explains type enum limitation, provides examples for since (ISO and relative), suggests typical values, and explains value formats. Adds value beyond schema.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' and lists example queries. It specifies data sources and distinguishes from sibling tool entity_profile, making the purpose highly 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 gives clear guidance on when to use entity_profile instead (for static profile), but does not explicitly state when not to use this tool beyond that. It provides context on the tool's coverage, making usage mostly clear.

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

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

Annotations provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. Description adds scoping by identifier, persistence details (authenticated vs anonymous, 24-hour retention), which adds value 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?

Concise yet comprehensive. Purpose, usage, and behavioral notes are front-loaded. Every sentence adds value, no redundancy.

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

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

Covers purpose, usage, storage details, and pairing with other tools. Lacks mention of behavior on duplicate keys (update or error) or return value, but overall sufficient for a write operation.

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

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

Schema coverage is 100% with descriptions for key and value. Description reinforces usage with examples but does not add significant new semantic detail beyond the schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later.' It provides specific examples of what to store (resolved ticker, target address, etc.) and distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use: 'when you discover something worth carrying forward.' Mentions pairing with recall and forget, guiding the agent on workflow.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description reveals internal cascading lookups, graceful degradation (if GLEIF/OpenFIGI unavailable, EDGAR identifiers still return), and output structure (identifiers labelled with source, unresolved listed explicitly). It also explains enrichment behavior for LEI/FIGI. No contradictions with annotations.

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

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

The description is front-loaded with examples, which is helpful, but it is verbose and includes several sentences that could be tightened (e.g., the detailed list of supported identifiers for company). While every sentence adds information, the length reduces scanability. A more compact version would improve conciseness.

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

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

Given the tool's moderate complexity (2 parameters, no output schema), the description covers input types, output structure, fallback behavior, and supported entity types. It does not explicitly state what happens if a value cannot be resolved (though 'unresolved' is mentioned), but overall it provides sufficient context for correct 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 description coverage is 100%, but the description adds value beyond the schema: it clarifies that company input accepts ISIN in addition to ticker/CIK/name, explains how ISIN is resolved, and lists specific drug examples. This supplements the schema's basic descriptions 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 explicitly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides multiple concrete examples (ticker, CIK, LEI, RxCUI) and clearly distinguishes the two entity types (company, drug). No sibling tool performs entity resolution, so differentiation is inherent.

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 direct guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that using resolve_entity 'replaces 2-3 manual lookups,' implying priority over alternative multi-step processes. While no explicit 'when not to use' is stated, the context makes it clear this tool is for name-to-ID resolution, and no sibling tool overlaps.

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 safe, idempotent, read-only operation. The description adds behavioral details: it internally calls ai_visibility_check for each entity, aggregates results, and returns a ranked list with score, confidence, and signal density. No contradiction with annotations.

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

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

Three sentences, front-loaded with purpose, then behavior and return structure. 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 no output schema, the description adequately covers return structure (ranked list) and key inputs. It also mentions the dependency on ai_visibility_check. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: 'First entry treated as the 'subject' for narrative; rest are competitors.' It clarifies entities are brand/competitor names and explains optional models and apiKey usage.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and ranks results. It distinguishes from the sibling ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a clear use case ('competitive AI-marketing audits') and example question, but does not explicitly state when not to use or contrast with alternatives like compare_entities. The context implies usage for multi-entity comparisons.

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 readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5–30 seconds, and sources_failed lists timeouts. It also describes the return structure without needing an output schema.

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

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

The description is front-loaded with the core purpose and usage, then covers return details, constraints, and performance. It is coherent but slightly verbose; a minor trim could improve conciseness 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 tool's complexity (composite check with two external sources) and no output schema, the description fully explains what is returned: summary block, per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timing, making it complete for the agent.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context about npm package names (scoped accepted) and version defaults (latest), but these are also in the schema. It does not add meaningful semantic nuances 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 starts with a clear composite purpose: 'should I add this npm package to my project' check in one call, specifying the verb (scan), resource (dependency), and the two data sources (deps.dev and bundlephobia). It distinguishes from siblings by focusing on npm packages and the specific question it answers.

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

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

Explicitly states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also notes limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear exclusion 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?

Discloses truncation at 200K chars with flag, embedding model (BGE-base-en), windowing (500-char overlapping, cosine), and return format (passages with offsets+similarity). Annotations already indicate safe, idempotent operation; description adds rich behavioral detail 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 dense sentences: first states purpose and usage, second adds technical constraints and output details. No redundant or filler content; 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?

Fully explains input limits (200K chars), output (passages with offsets/scores), embedding model, and pairing with sibling tool. No output schema but returns are clearly described. Complete for a search tool.

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

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

Schema covers all 3 parameters with descriptions; description adds practical context (e.g., text source examples, query examples, default limit) that helps an agent formulate inputs 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?

Clearly states semantic search inside a fetched record, with specific examples (SEC 10-K, article, tool result) and distinguishes from sibling ask_pipeworx_grounded by explaining the pairing pattern.

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

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

Explicitly describes when to use (record too big for prompt, save context) and pairs with ask_pipeworx_grounded for grounding; provides clear alternative to cramming entire document.

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

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

Adds significant detail beyond annotations: requires OAuth account, type-specific params, delivery constraints (email validation, SMS verification, webhook signing, auto-disable). 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?

Well-organized with clear structure (types listed, delivery channels detailed). A bit lengthy but each 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?

Covers all essential aspects: types, params, delivery, behavior (idempotent, non-destructive, requires auth). Adequate given complexity and 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 description enriches each parameter with examples, validation rules, and behavioral details (e.g., SMS cap, webhook signing). Goes well beyond schema.

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

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

Clearly states the action (create), the resource (subscription), and the output (returns subscription id). Distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides extensive context on when to use (monitoring live-data streams), supported types, and delivery options. However, lacks explicit when-not-to-use or alternative tool guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context by explaining that it returns example questions with tool+argument shape drawn from a live catalog, and that calling with no arguments gives a full spread while passing 'topic' focuses the results.

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 slightly long but front-loaded with purpose and every sentence adds value. It could be trimmed slightly, but overall it's 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 role as an onboarding entry point, the description fully conveys its purpose, usage, and output (category-bucketed example questions). No output schema exists, but the description compensates by explaining the return format.

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 the 'topic' parameter described. The description adds meaning by listing possible values (e.g., finance, pharma) and explaining the effect of omitting vs. providing the parameter, which goes beyond the schema's basic 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 as the onboarding entry point for agents who want to know what Pipeworx can do. It uses specific verbs like 'Returns category-bucketed example questions' and distinguishes it from sibling tools by noting it's for initial exploration.

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

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

The description explicitly advises to 'use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides clear when-to-use guidance, though it doesn't 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?

Beyond annotations (idempotentHint true, destructiveHint false), the description adds critical behavioral context: ownership enforcement, deactivation rather than deletion, and availability of historical events via 'recent_alerts'. This fully informs the agent of side effects and data persistence.

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

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

The description is three sentences, directly addressing purpose, constraint, and consequence. Every sentence adds value with no redundancy or fluff.

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

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

Given the simple input (single parameter) and presence of annotations, the description sufficiently covers purpose, ownership constraint, mutation behavior, and post-action data availability. No output schema needed as the tool is a void mutation.

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

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

Schema covers 100% of parameters with a clear description of 'id' as a UUID returned by subscribe. The tool description adds no further parameter semantics beyond reiterating ownership enforcement, which is behavioral rather than parameter-specific. Baseline score for high coverage.

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,' specifying the verb (cancel) and resource (subscription). It further clarifies ownership enforcement and the deactivation vs deletion behavior, distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description implicitly guides usage by noting ownership enforcement ('you can only cancel your own subscriptions') and explaining that historical events remain accessible via 'recent_alerts'. It does not explicitly name alternative tools or conditions for non-use, but the context is clear.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behaviors: the dual pipeline (SEC vs. grounded), the exact verdict values, the meaning of could_not_verify (with verification_error context) and unsupported, and the citation format. This is critical state information not visible from annotations or schema.

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

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

Though long, every sentence earns its place. It is front-loaded with trigger phrases and usage, then technical pathway details, return values, and a clear warning about error semantics. The bold 'IMPORTANT for callers' improves structure. No fluff or redundancy.

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

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

The tool is complex (two pipelines, multiple verdicts, error handling) and has no output schema. The description compensates fully by explaining the verdict enum, actual value with citation, reasoning, and the distinction between could_not_verify and unsupported. Also explains tolerance behavior. This is a complete picture for an agent to invoke correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds extra meaning for tolerance_pct, explaining it overrides implied tolerance and suggesting 1–2 for hallucination detection. It does not add significantly for claim, but the overall context helps usage. This exceeds 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 a specific verb+resource: 'natural-language claim verification against authoritative sources.' It lists trigger phrases and distinguishes itself from sibling tools by focusing on verifying factual claims, with a structured fast path for company-financial claims and a grounded pipeline for everything else. This is unambiguous and differentiates from broader research tools like deep_research.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It further segments usage by claim type (company-financial vs. any other) and highlights efficiency by replacing 4–6 sequential calls. While it doesn't name alternative tools, the scope is so clearly defined that no when-not guidance is necessary.

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