Google_ads

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds return format details (per-model score, confidence, signals, raw_response + combined view) and clarifies cost model (BYO key for Anthropic). No contradictions.

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

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

Three well-structured sentences: action+output, model details, use cases. No filler, every sentence adds value. Front-loaded with core purpose.

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

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

Despite no output schema, description explains return structure adequately. Covers all 4 parameters, use cases, and behavioral context. Complete for a read-only probing tool with straightforward output.

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

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

Schema description coverage is 100%. Description adds rich context for each parameter: entity examples, model options with default, _apiKey purpose and when required, context disambiguation help. Far exceeds schema basics.

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 verb 'probe' and resource 'LLMs for what they know about a business / brand / product / topic' with scoring output. It differentiates from siblings by focusing on brand visibility across models, distinct from general Q&A tools like 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?

Lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Provides model selection guidance (default vs. BYO key). Lacks explicit when-not-to-use or direct comparison to potentially similar siblings like scan_competitor_ai_presence.

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=false. The description adds valuable behavioral context: returns a structured answer with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This exceeds annotation coverage without contradiction.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH', then provides a dense but organized list of domains, triggers, examples, and escalation paths. Every sentence earns its place, and the structure flows logically from instruction to examples to alternatives.

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

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

Despite having no output schema, the description specifies the output format (structured answer with citations), scope (5,529 tools, 1,455 sources), and special considerations (works on all tiers, one call). It fully covers the tool's complexity and gives sufficient context for an agent to select and invoke it.

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, including aliases (q, text, input, query, prompt, question). The description supplements this with concrete examples of valid questions (e.g., 'current US unemployment rate'), which add semantic guidance beyond the schema's generic 'Your question or request in natural language', but does not introduce new syntax details.

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

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

The description clearly states the tool's function: routing questions to one of 5,529 tools across 1,455 sources and returning structured answers with citations. It uses a specific verb ('routes the question'), enumerates covered domains, and distinguishes itself from siblings by name-dropping ask_pipeworx_grounded and deep_research as alternatives.

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 instructs 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', listing trigger phrases like 'what is', 'look up', 'find'. It also provides step-up guidance: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad questions, clearly defining when to choose 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?

Goes beyond annotations by disclosing the experimental nature, current state (no active candidate, matches stable exactly), and the comparison/merge process with the stable router. This is valuable context not captured in the readOnly/idempotent hints.

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

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

The description is moderately concise but informative, with each sentence contributing. It is front-loaded with the core identity (beta version) and includes specific facts (5,529 tools, date). Slightly verbose in the last sentence but overall well-structured.

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

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

Covers the tool's identity, functionality, current operational state, relationship to ask_pipeworx, and experimental purpose. No output schema exists, but the description explicitly notes 'same response shape' as ask_pipeworx, making the tool's behavior sufficiently complete for an agent.

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

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

Input schema provides 100% coverage with clear descriptions for all six parameters (aliases for 'question'). The description adds no new parameter-level detail beyond referencing identical arguments to ask_pipeworx, which is acceptable per the baseline for 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 the tool as 'Beta version of ask_pipeworx: identical universal router' with same tools, arguments, and response shape. It explicitly differentiates from the stable sibling by highlighting experimental routing improvements, making its purpose and distinction 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?

Provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies it is not a fallback ('Falls back to nothing — this IS a full working router'). This gives clear when-to-use versus the stable alternative.

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

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

Beyond the annotations, the description specifies the exact success and refusal response structures, grounds the answer in tool results only, and discloses an extra LLM call cost. This adds rich behavioral context that the annotations alone do not provide, and there is no contradiction.

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

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

The description is four sentences with the core purpose front-loaded. It is detailed and each sentence adds value, though the enumeration of refusal reasons and the specific tool/source counts add some length without directly affecting decision-making. Overall, it remains 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?

With no output schema, the description fully specifies both success and refusal output objects, explains the internal routing and grounding behavior, and covers use cases and cost trade-offs. This makes the tool self-contained enough for an agent to understand and 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?

The input schema already documents the sole parameter (question) with alias descriptions at 100% coverage. The description does not add extra parameter semantics, but the schema is sufficient, so baseline 3 applies.

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

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

The description clearly defines this as a hallucination-resistant answer mode for high-stakes reads. It distinguishes from the sibling ask_pipeworx by explicitly contrasting the grounded extraction behavior and cost difference, making the tool's unique purpose unambiguous.

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

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

Explicitly states when to use (answers quoted, cited, acted on; high-stakes domains like financial verdicts, legal claims) and when to prefer the alternative (casual lookups with ask_pipeworx). This direct comparison provides clear decision guidance for an agent.

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

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

The description extensively details behavioral traits beyond annotations, including resolution confidence handling, parent event extraction, news fields with fallback mechanisms, safety short-circuits for low-confidence matches, closed market handling, wide-spread warnings, and resolution-rule risk parsing. This far exceeds what the readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations convey.

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

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

The description is front-loaded with the main purpose but becomes lengthy with many details and examples. While each section adds value, it could be more concise. Nonetheless, the structure is logical: purpose, usage, behavior, response details, safety notes.

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

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

For a tool with 3 parameters and no output schema, the description is remarkably complete. It covers resolution logic, fan-out behavior, response shapes, confidence scoring, parent events, news fields, safety mechanisms, and cancellation rules. No significant gaps are apparent.

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 some context (e.g., default depth is thorough, recommend false for include_raw) but does not significantly enrich parameter meaning beyond the schema. The examples clarify input formats but are also present in schema examples.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research) and resource (Polymarket bet) with concrete examples like 'should I bet on X'. It distinguishes from sibling tools (e.g., polymarket_edges) by focusing on comprehensive data aggregation and evidence packets.

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

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

Explicit usage guidance is provided: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives conditional instructions, such as inspecting market_match_confidence and parent_event before trusting analysis. Multiple category-specific fan-out examples clarify when which sub-tools are invoked.

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

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

The description adds significant behavioral detail beyond annotations, such as how fiscal year handling works for companies (AAPL Sep, NVDA Jan) and that results are sorted by primary metric. It also explains the data sources and return format (paired data + citation URIs). No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is efficient, front-loading the purpose and trigger phrases. It packs substantial detail into a few sentences without being verbose. Slightly long but justified given the complexity of the tool.

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

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

Given the absence of an output schema, the description adequately covers return data (paired data + citation URIs) and sorting behavior. It also explains the data sources and entity-specific differences, providing enough context for the agent to understand inputs and outputs.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaningful context: explaining that type='company' pulls financial data and type='drug' pulls adverse event/trial data, and clarifies that values should be tickers/CIKs or drug names with examples. This adds value beyond the schema.

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

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

The description clearly states it performs side-by-side comparison of 2-5 companies or drugs, specifying the exact data pulled (financials from SEC EDGAR/XBRL for companies; FAERS counts, FDA approvals, trial counts for drugs). It also distinguishes itself from siblings like entity_profile by recommending it over sequential single-pack lookups.

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

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

Explicitly provides trigger phrases ('compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies') and strong guidance to prefer this tool over sequential lookups. It also clarifies the entity types and what each pulls, helping the agent decide when to use it.

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

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

The description adds rich behavioral context beyond annotations: account requirements, parallel tool routing, findings packet contents (verbatim evidence + confidence + source + citation), explicit gaps[] vs never invented, contradictions[], time expectations, and excerpting behavior. It also explains hop/citation semantics, far exceeding the basic readOnly/destructive hints.

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

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

The description is long but information-dense, covering prerequisite, differentiation, mechanics, output, limitations, and performance. It is front-loaded with the account requirement and 'not open-web search' clarification, and every sentence serves a purpose; however, it could be tightened without loss.

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

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

With no output schema, the description fully specifies the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop) and sets expectations for latency and failures. It also covers alternatives and limitations, making it complete for agent invocation.

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

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

Schema coverage is 100%, and the schema already documents the depth levels in detail (including the paid note for thorough). The tool description adds minimal additional parameter-specific info beyond what the schema provides, so it does not meaningfully enhance parameter understanding.

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

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

The description uses a specific verb ('research') and resource ('1455 STRUCTURED data sources'), and explains it decomposes questions and routes them to 5,529 tools in parallel. It explicitly distinguishes from sibling ask_pipeworx ('For a single lookup use ask_pipeworx') and from open-web search, making its unique purpose 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 explicitly states when to use: 'Best for broad/multi-part questions over structured data' and when not: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives account prerequisites and warns that depth:'thorough' needs a paid plan, providing complete usage guidance.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds value by detailing return format (top-N tools with schemas, ready to call) and no second lookup needed.

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

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

Concise, front-loaded, each sentence adds value: purpose, example domains, return format, usage tip. No wasted words.

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

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

No output schema, but description adequately explains return format: top-N tools with names, descriptions, and full schemas. Sufficient for an agent to understand what it will receive.

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 descriptions. Description mentions query as natural language but adds little beyond schema; baseline 3 is appropriate.

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

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

Description clearly states 'Find tools by describing the data or task' with specific verb and resource. It distinguishes itself from sibling tools which are domain-specific; this is a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available' and lists example use cases like SEC filings, FDA drugs, etc., providing clear when-to-use guidance.

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

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

The description adds behavioral context beyond the annotations: it reveals that the tool fans out across multiple sources, notes a specific upcoming API sunset (USPTO PatentsView May 2025) and soft-fail behavior, and mentions a fallback chain (GDELT→GNews). This transparency is valuable for an agent to manage expectations.

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 reasonably concise for the amount of information conveyed. It front-loads with example queries and then lists data sources and return fields. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for return fields). No fluff detected.

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

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

Given the tool's complexity (multiple sources, no output schema), the description thoroughly explains what is returned: cik, company_name, recent_filings with URIs, fundamentals (with specific fields), patents with sunset note, news with fallback, and LEI. This is sufficient for an agent to understand the output without an output schema.

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

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

With 100% schema coverage, baseline is 3, but the description adds meaning: it specifies that value can be a ticker or zero-padded CIK, explicitly states that names are not supported, and clarifies that type is currently only 'company'. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: providing a full cross-source profile of a US public company. It uses specific verbs ('profile', 'brief me') and resource ('company'), and distinguishes from sibling tools like resolve_entity by noting that names are not supported. It also contrasts with chaining multiple 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using resolve_entity first if only a name is available, and notes that person/place types are coming soon. This provides clear when-to-use and when-not-to 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 set destructiveHint=true, so the description does not need to emphasize destructiveness. However, it adds useful context about the types of data to clear (stale, sensitive), which adds value beyond the annotation.

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

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

Two sentences, first sentence states the core function, second provides usage context. No fluff, every word earns its place.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose and usage. It includes both what it does and when to use it, making it self-sufficient.

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

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

The only parameter 'key' is already described in the schema as 'Memory key to delete'. The description doesn't add additional semantics beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It also distinguishes from sibling tools like 'remember' and 'recall' which are explicitly mentioned.

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: when context is stale, task is done, or to clear sensitive data. It also name-drops related sibling tools to help with 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 fully declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is clear. The description adds what metrics are returned but doesn't disclose any additional behavioral traits (e.g., data aggregation level, pagination, rate limits). With annotations covering safety, a score of 3 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 two sentences, no fluff. It efficiently states the purpose, what's returned, and a use case. Every sentence adds value.

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

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

Given that an output schema exists, the description need not explain return values in detail. It covers the core purpose and typical use cases. For a read-only metrics tool with good annotations and complete schema, this is sufficient.

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

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

All 5 parameters have descriptions in the input schema, so schema coverage is 100%. The description does not add new detail beyond what the schema already provides (e.g., date format, optional filters). Baseline 3 is correct when the schema carries the load.

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

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

The description clearly states the tool returns performance metrics for campaigns over a date range, including specific KPIs (impressions, clicks, etc.). This distinguishes it from siblings like gads_list_campaigns which returns a campaign list without metrics, and gads_get_campaign which returns a single campaign's details.

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

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

The description says 'Use to analyze campaign effectiveness or compare performance trends,' which provides context but no explicit guidance on when not to use it or alternatives. For example, if the user needs raw data or a search, gads_search might be more appropriate. Sibling tools are not mentioned.

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 no extra behavioral context beyond its basic function. It does not contradict annotations.

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

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

Two sentences efficiently convey the action, returned data, and use case. No extraneous information.

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

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

For a simple read tool with annotations and output schema present, the description covers purpose, usage, and key return fields. It is sufficient for an AI agent to understand and invoke 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?

Input schema has 100% description coverage for both parameters. The description does not add new meaning beyond the schema; it simply reinforces that the tool gets settings for a campaign, which implies the campaign_id parameter.

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

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

The description clearly states the verb 'Get', the resource 'specific campaign', and lists returned fields (name, status, budget, etc.). It distinguishes from siblings like 'gads_list_campaigns' and 'gads_campaign_metrics' by focusing on detailed settings of a single campaign.

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

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

The description explicitly advises 'Use to review or audit a campaign's current setup', providing clear guidance. However, it does not mention when not to use this tool or suggest alternatives (e.g., using gads_campaign_metrics for metrics, or gads_list_campaigns for listing).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, providing safety context. The description adds value by specifying what data is returned (ad group names, IDs, statuses, CPC bids) and the intended use cases, which helps the agent understand the behavior beyond the annotations.

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

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

The description is two sentences, front-loading the action and quickly covering what is returned and when to use it. Every sentence contributes value without redundancy.

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

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

Given the tool's simplicity (4 parameters, read-only, output schema exists), the description covers the essential aspects: purpose, key parameters, returned fields, and use cases. It does not discuss pagination or default limit details, but that is a minor gap for a listing operation.

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

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

Schema coverage is 100%, so the input schema already describes all four parameters well. The description mentions filtering by campaign ID (campaign_id) but does not add significant extra meaning beyond the schema. It does not clarify the limit default or status options, which are already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (list ad groups), the resource (within a campaign), and the unique identifier (campaign ID). It lists returned fields (names, IDs, statuses, CPC bids) and provides a use case (explore campaign structure or select an ad group), distinguishing it from sibling tools like gads_list_campaigns.

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

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

The description includes a usage statement ('Use to explore campaign structure or select an ad group for analysis') which implies when to use, but does not explicitly mention when not to use or provide direct comparisons to alternative tools. The context of sibling tools helps, but the description lacks explicit 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=true, idempotentHint=true, and destructiveHint=false, so the description is not burdened with safety disclosure. It adds value by specifying the fields returned (names, IDs, statuses, budgets, types). No contradictions with annotations. However, it could mention pagination or performance implications for large accounts.

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 action verb 'List'. Every sentence adds value: first states purpose and return data, second gives usage guidance. No wasted words.

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

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

Given the presence of an output schema and robust annotations, the description is complete. It covers the tool's purpose, return values, and a common use case. The parameter count (3, 1 required) is moderate and well-addressed by the schema.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add meaning beyond the schema (e.g., does not explain limit default behavior or customer_id format). Baseline 3 is appropriate as the schema already provides the necessary semantics.

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 'List all campaigns' with a specific verb and resource. It lists the return fields (names, IDs, statuses, budgets, types) and provides a use case: overview account structure or find a campaign ID. This effectively distinguishes it from sibling tools like gads_campaign_metrics or gads_get_campaign.

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

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

The description gives explicit usage context: 'Use to overview account structure or find a campaign ID for detailed analysis.' While it does not mention when not to use or directly compare to siblings, the guidance is clear and actionable. The context signals and sibling list further aid differentiation.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description need not repeat these. The description adds no behavioral traits beyond annotations, but does not contradict them. A score of 3 is appropriate as the description adds marginal behavioral context.

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

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

The description is two sentences: one for the core action, one for usage context. It is front-loaded, concise, and contains no redundant information. Every sentence adds value.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers usage context. It could mention return format or limitations, but completeness is high for a tool with strong structured metadata.

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

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

Schema coverage is 100%, with both parameters documented. The description adds examples of filtering and aggregation, providing context beyond schema but not essential new semantics. Baseline 3 is justified as the schema does the primary work.

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 runs custom GAQL queries against Google Ads data, using specific verbs and resource. It distinguishes from sibling tools like gads_campaign_metrics by emphasizing advanced analysis and custom dimensions, making the purpose unambiguous.

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

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

The description provides clear context for usage using 'Use for advanced analysis' and examples, but does not explicitly state when not to use this tool versus alternatives like gads_campaign_metrics or gads_list_campaigns. The guidance is adequate but lacks exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by detailing the process: fetches the page, extracts title/description/key links, and emits standard markdown format. This explains behavior beyond annotations, though it doesn't cover edge cases like rate limits or error handling.

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

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

The description is two sentences, front-loaded with the core purpose and output, followed by use cases. Every sentence conveys essential information without redundancy. No wasted words.

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

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

Given the low complexity (2 parameters, no output schema, no nested objects) and rich annotations (readOnly, openWorld, idempotent), the description fully covers what the tool does, its inputs, output format, and typical use cases. No gaps are apparent.

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 defines both parameters (url and max_links). The description reinforces the URL parameter but adds no new semantic meaning beyond what the schema provides. For max_links, the schema already includes default and max values; description does not elaborate. 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes itself from sibling tools, which cover unrelated topics like ads (gads*), research (deep_research), and arbitration (polymarket*), making its purpose unique.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitor. It implies when to use (for indexing) but does not specify when not to use or name alternative tools, though no sibling tool overlaps in functionality. Lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields (id, type, etc.) and scopes to 'the caller's subscriptions.' 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?

Two sentences, first explains purpose and output, second gives usage guidance. No filler, front-loaded with key information.

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

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

For a simple list tool with one optional parameter, all aspects are covered: purpose, return fields, usage context, and safety. No output schema is needed since return fields are described.

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

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

Schema coverage is 100% with the parameter include_inactive fully described. The description does not add parameter-level details, but baseline is 3 due to 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 'List the caller's active subscriptions' and specifies return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by implying this is for reviewing existing 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?

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use this tool versus alternatives (subscribe, unsubscribe).

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 no safety hints (all false), so the description must carry the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), and scope constraints ('ONLY for tools served by this Pipeworx connection'), far beyond what structured fields provide.

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

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

The description is a single dense paragraph but every sentence adds necessary information: purpose, usage triggers, exclusion, best practices, token mechanism, rate limits, and quota. Though not bulleted, it's efficiently written and front-loaded with the core purpose.

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

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

Given 4 parameters, nested objects, and no output schema, the description covers all needed aspects: what the tool does, when to use, what to avoid, the claim_token response flow, and rate limiting. It even tells the team's review cadence. Nothing critical is omitted.

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 schema already documents each parameter with descriptions. The description adds extra semantics by explaining how to use `claim_token` and advising not to paste end-user prompts, enriching the `message` field. Baseline 3 plus added value justifies 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 opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' clearly defining the action and target. It distinguishes from sibling tools (all research/monitoring tools) by specifying it's for feedback to the team.

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

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

Explicitly lists scenarios (bug, feature/data_gap, praise) and gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary when-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: data derived from CF analytics-engine, no PII, caching (5min-1h). This goes beyond annotations to inform the agent about data source, privacy, and staleness.

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 4 sentences, front-loaded with the core purpose, then use cases, then technical details. No wasted words; every sentence adds value.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, use cases, data origin, privacy, and caching thoroughly. It is fully adequate for the 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% and the schema description already explains the window parameter (enum values and semantics of short vs long windows). The description reiterates the windows but adds no new parameter meaning beyond what the schema provides.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a recent window, using a specific verb 'returns'. It distinguishes itself from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing on trending usage rather than general discovery or Q&A.

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?

Three explicit use cases are provided (discovering hot data sources, confirming canonical tool, seeing alignment). While it doesn't state when not to use or directly name alternatives, the use cases are clear and helpful for decision-making.

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 safe annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses key behavioral traits: monotonicity violations, partition checks, semantic anchor, partition filter, and fill check with realizable edge warnings. 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 thorough but somewhat lengthy, including detailed mechanism and response structure. However, it front-loads the purpose and key modes. Could be slightly more concise without losing critical details, but the complexity justifies 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?

Despite no output schema, the description comprehensively covers response fields (opportunities[], partition_check, fill check) and edge cases (skipped_low_similarity, placeholders_filtered). Complete context for a complex tool with multiple modes.

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 significant meaning beyond schema: it clarifies mutual exclusivity of event and topic, gives example values, and explains what each mode does in detail. This fully compensates for any schema brevity.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, and distinguishes three modes (trending, event, topic). This differentiates it from sibling tools like polymarket_edges and polymarket_edge_tracker.

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

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

The description explicitly specifies when to use each mode: no args for trending, event for a specific market slug, topic for cross-event scanning. It also explains why cross-event mode can catch patterns that single-event misses, and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: caching policy (KV-level 1h cache), three response segments, diagnostics, Fed notes, and detailed explanations of edge calculation, slippage, and Kelly sizing. 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 lengthy but highly informative, with front-loaded purpose and detailed inline explanations. Every sentence adds value, though a more structured format (e.g., bullet points) could improve readability without losing content.

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

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

Despite having no output schema, the description comprehensively explains the response structure (by_segment, fed_candidates, _diagnostics) and the reasoning behind Fed exclusions. All 9 parameters are covered with usage context, making the tool fully understandable for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant extra context beyond schema, such as explaining how min_partition_leg_kelly interacts with partition arbs, and providing usage tips for slippage_pp. This justifies a 4.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It includes the specific use case 'what should I bet on today' and distinguishes the tool from siblings by its unique model families and focus on Pipeworx disagreement.

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

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

The description provides context for when to use the tool ('what should I bet on today') and gives detailed usage tips for parameters (e.g., 'Bump for very thin partitions; drop to 0 if you have a smarter fill model'). However, it does not explicitly state when not to use the tool or compare to sibling tools for exclusion.

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

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

The description extensively discloses behavior: it computes trend and decay, explains negative values, details expired opportunities, and notes snapshot writing conditions and TTL. This goes well beyond the annotations (readOnlyHint, idempotentHint, etc.), providing clear operational expectations.

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

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

The description is detailed but efficiently structured, starting with a core question then expanding. The use of sub-sections (tracked[], expired[], snapshot_dates[]) is clear. A minor redundancy exists (explaining both in text and parentheses), but overall it is well-organized and not overly verbose.

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

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

Given no output schema, the description fully explains the response structure and fields, including meanings of trend values and decay calculation. It also notes limitations like TTL and snapshot gaps. This provides complete guidance for an agent to use the tool effectively.

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

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

The input schema already describes both parameters (days, window) with defaults. The description adds value by specifying clamp ranges (2-30 days), default values (14, '1wk'), and the meaning of the window parameter ('snapshot family'). It also explains how days affects history depth.

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 tool as providing edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?'), distinguishing it from sibling tools like polymarket_edges which likely provide current edge data.

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

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

The description explains when to use this tool—analyzing edge longevity and decay—and gives context that a 3-week-old wide edge is different from a fresh one. It mentions limits (60-day TTL, snapshot availability) but does not explicitly specify when not to use or name alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, covering safety. The description adds context about it being a check (not executing trades), walking the ladder, returning verdicts, and the risk of partial fills. No contradiction with annotations.

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

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

The description is well-structured: purpose statement first, then REQUIRES clause, then separate sections for single-market and basket modes, ending with usage guideline. Every sentence adds value; no redundancy. Front-loaded with key information.

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

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

The description covers both modes, return fields (e.g., top_of_book, vwap_fill_price, verdict), and critical warnings about partial fills. While lacking a precise output schema, it provides enough context for an agent to understand expected outputs. Slightly verbose but complete for a safety-check tool.

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

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

Schema coverage is 100% with descriptions. The description adds significant value: explains default behaviors (e.g., side auto default in basket mode), interpretation of size_usd (max spend on buys, target proceeds on sells; for basket, settlement notional), and clarifies the REQUIRES condition.

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes, each with specific return values. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk.

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

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

Explicitly states when to use: 'USE THIS before acting on 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, and partial basket fills convert arb into unhedged directional position.

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, openWorld, idempotent), the description details how spreads are computed, explains compatibility_warning cases (non-equivalent bet shapes, semantically unrelated events), temporal alignment implications, and skipped cross counters. No contradictions with annotations.

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

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

The description is comprehensive but somewhat verbose. It is well-structured with sections for modes, response, and safety fields, but contains redundant explanations. Could be tightened without losing clarity.

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

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

With 3 parameters and no output schema, the description adequately explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases. It covers all necessary behavioral 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 coverage is 100%, providing definitions for all three parameters. The description adds meaning by explaining the two modes, listing allowed topics, and clarifying how explicit tickers override the topic mapping. This adds context beyond the schema.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same question. It distinguishes two modes (topic shortcuts vs explicit tickers) and explains what the tool outputs, including safety fields. This differentiates it from siblings like polymarket_arbitrage.

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

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

The description explicitly explains when to use each mode, warns that most pre-mapped topics return compatibility warnings and may not be tradeable, and contrasts with sibling tools. It sets clear expectations about rarity of real spreads.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds value by explaining the retrieval mechanism, listing behavior when key omitted, scoping, and pairing with siblings. No contradictions.

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

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

The description is concise with three sentences. It front-loads the main action and efficiently adds context and pairing instructions. No redundant or unnecessary words.

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

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

Given the tool has only one optional parameter and no output schema, the description covers all necessary aspects: purpose, usage, behavior, scoping, and relationship to siblings. It is complete without being verbose.

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 parameter 'key' with description and examples. The tool description adds clarity by explaining the behavior when the key is omitted (list all keys), which is not fully captured in the schema. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: retrieve a value by key or list all keys when omitted. It specifies the verb (retrieve/list), resource (saved values), and context (previously saved via remember). It distinguishes itself from siblings remember and forget.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also notes scoping by identifier. However, it does not explicitly state when not to use it or mention alternatives beyond remember/forget.

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=false. The description adds key behavioral details: it can mark events as read (mark_read parameter), affecting subsequent calls. This does not contradict annotations but adds useful nuance.

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 compact paragraph with clear front-loading of purpose, followed by parameter details, side effects, and alternative access. Every sentence adds value with no redundancy.

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

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

The description fully explains the return value (source, citation_uri, raw event payload) and the effect of key parameters. It also addresses polling and alternative access. Without an output schema, this is sufficient for an AI agent to understand what to expect.

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. The description adds examples (e.g., filter by type 'sec_8k') and explains the effect of mark_read, which is beyond the schema. However, it does not elaborate on 'unread_only' or 'limit' beyond what the schema provides.

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

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

The description clearly states the verb 'pull' and the resource 'fired events from your subscription feed.' It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on retrieving alert events rather than managing 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 mentions polling works fine and points to an alternative HTTP endpoint for scripts/dashboards, giving context on usage. However, it does not explicitly exclude when not to use this tool or contrast it with other sibling tools like recell or recent_changes.

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

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

Annotations already mark it as read-only, idempotent, non-destructive. The description adds behavioral context: it fans out to multiple sources, has a specific fallback (GDELT→GNews), soft-fails for USPTO, and returns structured changes with citation URIs.

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

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

The description is relatively concise for its breadth, but it packs many details into a single paragraph. Minor structure improvements could enhance readability, but overall it's 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 tool's complexity (multiple data sources, date formats, fallback, return structure) and no output schema, the description provides complete context: it lists sources, explains fallback, describes return format, and notes the USPTO limitation.

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%. The description reinforces parameter meaning with examples (e.g., ISO date vs relative shorthand, ticker vs CIK) and usage recommendations (e.g., '30d' or '1m' for typical monitoring).

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: providing a change feed for a company with recent filings, news, and patents. It uses clear verb phrases like 'What's new with X' and distinguishes from the sibling tool 'entity_profile'.

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

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

The description gives clear when-to-use guidance (for time-windowed recent changes) and when-not-to-use (use entity_profile for static profiles regardless of window). It also explains fallback behavior for news sources.

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 write, idempotent, non-destructive. The description adds key details: scoped by identifier, persistence duration (24h for anonymous), and that it's a key-value store. Could mention overwrite behavior more explicitly, but overall 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?

Several sentences but each adds value: purpose, usage cues, technical details, and sibling references. Front-loaded with primary purpose. No fluff, but slightly longer than minimal.

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 simplicity (2 string params, no output schema), the description covers everything an agent needs: what, when, how, scope, persistence, and related tools.

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

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

Schema already covers both parameters with descriptions. The description adds practical examples for key naming conventions (e.g., 'subject_property') and value content, which helps the agent choose appropriate values.

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

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

The description clearly states the tool saves data for reuse later, with concrete examples (ticker, address, preference). It distinguishes from sibling tools recall and forget by naming them and explaining the memory lifecycle.

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') and mentions alternatives (recall, forget). Also specifies scope differences between authenticated and anonymous sessions.

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?

Even with strong annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral context: it discloses that each call cascades through multiple lookup endpoints, that LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI are unavailable, and that unresolved identifiers are explicitly reported under `unresolved` rather than omitted. It also notes source attribution for each identifier. This exceeds the bare annotation safety profile and provides valuable operational transparency.

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

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

The description is long but information-dense. It front-loads with user-style query examples to set intent, then systematically covers supported types, data sources, failure behavior, and practical benefit. Every sentence adds value, though the parentheticals and source details could be tightened slightly without losing meaning. It is appropriately structured for a complex tool with two distinct 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 the tool's complexity (two entity types, multiple identifiers, external sources) and the absence of an output schema, the description thoroughly explains what will be returned: for company (CIK, ticker, company_name, LEI with ownership, FIGI), for drug (RxCUI, ingredient, brand, citation), and the `unresolved` field for failed lookups. It also explains graceful degradation and the cascading nature. This is sufficient for an agent to understand the tool's behavior and output without needing a separate 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?

The schema descriptions are minimal (type enum and value as string), but the tool description substantially enriches both parameters. For 'type' it explains what each enum value covers and what data is returned; for 'value' it provides concrete examples (AAPL, 0000320193, 'ozempic', 'metformin') and clarifies acceptable formats for company (ticker, CIK, or name) and drug (brand or generic). This is much more than the schema provides.

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

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

The description clearly states the tool's core function: resolving user-spoken names to canonical identifiers (ticker, CIK, LEI, RxCUI, etc.). It uses a specific verb ('resolve') and resource ('entity'), and supports two distinct types (company, drug) with detailed output examples. This distinguishes it from sibling tools like entity_profile, which likely provides profile data rather than identifier lookup.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what inputs are accepted for each type and notes that it replaces 2-3 manual lookups. However, it does not explicitly reference sibling tools as alternatives or provide exclusion criteria (e.g., 'do not use if you already have a canonical ID'), so it falls slightly short of the highest standard.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list with score, confidence, signal density. 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?

Two sentences, each earning its place: first states purpose, second details process and utility. No redundant words. Front-loaded with key action.

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

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

Description covers purpose, process, output format, and use case. Since no output schema exists, it adequately describes the return structure (ranked list with metrics). Could mention edge cases like entity count limits, but schema constraints may handle that.

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

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

All parameters have schema descriptions (100% coverage). Description adds context beyond schema: 'First entry treated as the subject for narrative; rest are competitors' enhances understanding of 'entities' parameter. Also explains the role of 'models' and 'context' 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?

Description explicitly states 'Compare AI visibility across multiple entities side-by-side' with specific verb and resource. Clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (likely more general).

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 a concrete use case: 'competitive AI-marketing audits' with example question. Implicitly suggests when to use this over ai_visibility_check by mentioning it probes multiple entities, but doesn't 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?

The description goes beyond annotations by detailing the fan-out behavior, partial failure handling, and measurement delays. It adds context about sources_failed and return format, which annotations don't cover. No contradiction.

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

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

The description is comprehensive but slightly long. However, every sentence serves a purpose, and the most important info is front-loaded. Minor deduction for verbosity.

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 lack of output schema, the description fully specifies the return fields, behavioral constraints, and ecosystem limitations. It addresses all likely agent questions about usage and outcomes.

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

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

Schema coverage is 100%, and the description adds value by mentioning scoped packages and default version behavior. It also clarifies the return summary block fields, enhancing understanding beyond the schema.

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

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

The description clearly states it's a composite check for npm packages, specifying the resources (deps.dev, bundlephobia) and the types of queries it answers (safety, popularity, size). It distinguishes from sibling tools by focusing on package dependency scanning.

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

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

The description explicitly says 'Use whenever an agent asks...' and provides clear context for when to use, alternative ecosystems, and graceful degradation. It also warns about potential timeouts for bundlephobia.

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 false. The description adds rich details: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), character limit (200K chars with truncation flag), and return fields (offsets and similarity scores). 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?

Three sentences, well-structured, front-loaded with purpose. Every sentence adds necessary context without redundancy.

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

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

Given no output schema, the description explains return format (top-N passages with offsets and similarity scores). Covers input constraints, pairing info, and limits. Complete for a 3-parameter 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% but description adds value: for 'text' specifies max ~200K chars, for 'query' gives concrete examples, for 'limit' notes default 5 and range 1-20. Also mentions truncation behavior for long inputs.

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 states it performs semantic search inside a fetched record, using specific verbs like 'search inside', 'pass the text', and 'get back passages'. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative tool (ask_pipeworx_grounded). Implies when not to use by the condition of record size.

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

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

Adds significant behavioral details beyond annotations: OAuth requirement, SMS cap (10/day), phone verification, webhook auto-disable after 10 failures, HMAC signing. 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?

Packed with useful info, front-loaded with main purpose. Slightly lengthy but each sentence adds value. Could benefit from more structured layout (e.g., bullet points).

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 creation process, account requirement, types, delivery details, and limitations. Missing explicit return structure beyond 'new subscription id' (e.g., webhook_secret). Still fairly complete for a creation 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%, but description enriches with concrete examples for each type's params and detailed delivery constraints (phone verification, SMS cap, webhook HMAC). 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 states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This is a specific verb+resource, distinct from siblings like unsubscribe and list_subscriptions.

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

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

Provides clear context: requires Pipeworx OAuth account, lists supported types with examples, delivery channels. Does not explicitly exclude alternatives, but purpose is clear enough for selection.

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

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

Annotations already provide safety hints (readOnly, openWorld, idempotent). Description adds useful context: it returns category-bucketed questions with exact tool+argument shapes, and that it can be called with no arguments or with a topic. 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 somewhat long but efficiently packed with information. It is front-loaded with the purpose and usage guidelines, and every sentence adds value. Could be slightly more concise.

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

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

Given the tool's role as an onboarding tool with many categories and no output schema, the description provides comprehensive coverage: lists categories, explains return format, and indicates first-use scenario. Fully sufficient for an agent to understand when and how to invoke.

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

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

Schema coverage is 100% with a clear description of the 'topic' parameter. The description provides additional context on possible values and behavior when omitted (full spread vs focused). 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?

The description clearly states it is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs like 'returns' and distinguishes from siblings by being the first tool to use when unsure of Pipeworx capabilities.

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: 'Use this FIRST when you do not yet know what Pipeworx can do'. Also explains how to use the optional topic parameter for focus, and mentions it reveals how to call meta-tools.

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

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

Adds behavioral context beyond annotations: row is deactivated (not deleted) and historical events remain available via recent_alerts. 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 concise sentences, front-loaded with purpose. Every sentence adds value without redundancy.

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

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

Complete for a simple tool with one parameter and no output schema. Covers ownership, behavior, and historical data implications.

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 adequate parameter description. Description does not add extra meaning beyond what the schema provides, so baseline score 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?

Clear verb 'Cancel a subscription by id' specifies action and resource. Distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on valid use cases. Does not explicitly mention alternatives but context is clear.

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

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

The description provides extensive behavioral context beyond the annotations: it explains the routing logic, the meaning of each verdict, and critically warns that 'could_not_verify means the check did not happen... must not be shown as one.' It also discloses that the tool returns evidence with citations and reasoning, which the annotations do not convey. 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 long but well-structured and front-loaded with natural-language triggers. Every section serves a purpose: usage, routing, output format, and important caveats. It uses clear labels ('IMPORTANT for callers') to highlight critical behavioral notes, and there is no redundant or fluff content.

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

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

There is no output schema, so the description must fully specify return values, and it does: it lists the verdicts, the 'grounded or structured actual value with pipeworx:// citation,' and reasoning. It also covers edge-case semantics (unsupported vs. could_not_verify) and the two routing paths, leaving no significant gaps for an agent to invoke 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?

The input schema covers all parameters with detailed descriptions, so baseline is 3. The description adds a few illustrative examples (e.g., 'Apple's FY2024 revenue was $400 billion') and mentions 'exact percent-delta math,' but it does not significantly enrich parameter semantics beyond what the schema already provides.

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

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

The description clearly defines the tool as 'natural-language claim verification against authoritative sources' and specifies its scope (fact-checking user statements). It distinguishes itself by describing the two processing paths (SEC EDGAR for company financials, grounded pipeline for other claims) and the output verdicts, which differentiates it from sibling tools like ask_pipeworx_grounded or 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?

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides usage nuance by differentiating financial claims from other factual claims and mentions it replaces multiple sequential calls. However, it does not explicitly state when not to use it or point to alternative tools, so it falls short of a 5.

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