Facebook_ads

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: default model is free, Anthropic requires BYO key, _apiKey is passed straight through, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This goes beyond annotations.

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

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

The description is concise (3-4 sentences) with no fluff. It front-loads the main purpose, then provides key details (default model, key requirement, return format) efficiently.

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

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

Despite no output schema, the description fully explains the return structure (per-model + combined). It covers cost implications (free vs BYO key), parameter options, and typical use cases. This is complete for a probe tool of this complexity.

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

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

Schema description coverage is 100%, but the description enriches understanding: it explains that 'models' can include 'workers-ai' (free default) and 'anthropic' (requires _apiKey), omitting models defaults to workers-ai, and 'context' disambiguates entities. 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It distinguishes itself from siblings like 'ask_pipeworx' (which queries a single AI) and 'entity_profile' (which provides entity info) by focusing on AI visibility scoring across multiple models.

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

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

The description lists specific use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also clarifies when to use the optional _apiKey parameter (for Anthropic probing). However, it does not explicitly state when not to use the tool or provide direct comparisons to sibling tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint. Description adds that it returns structured answers with citation URIs and routes to verified sources. 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?

Front-loaded with key usage advice. Some repetition in listing aliases, but each sentence adds value. Could be slightly more concise, 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?

Despite having only one required parameter and no output schema, the description fully covers the tool's purpose, domain, and behavior. Examples ground the abstract description.

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 6 aliases for 'question'. Description explains the main parameter and lists examples, adding value beyond the schema by specifying what kinds of questions are accepted.

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 it routes factual questions to authoritative sources, distinguishing itself from web search and other sibling tools. Uses specific verb 'routes' and resource '3,751 tools across 886 sources'.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides concrete examples and query patterns. Gives clear guidance on when to use and lists many use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds important behavioral context: it routes like ask_pipeworx but extracts answer using only tool result, returns explicit refusal on failure, and mentions the extra LLM call cost. 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 fairly long but front-loaded with the key purpose and details. Every sentence adds value, covering purpose, routing, return format, refusal reasons, use cases, and cost comparison. It is efficient for the complexity, though slightly wordy.

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

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

Given the complexity (tool with refusal modes, comparison to sibling), the description is quite complete. It details the return object even without an output schema. It lacks limits like maximum question length but is sufficient for its purpose.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra value beyond noting aliases and that the question is in natural language. Baseline 3 is appropriate.

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

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

The description clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes from 'ask_pipeworx' by noting the extra cost and preferred use cases. It specifies the return format and refusal reasons, making the purpose precise and unambiguous.

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

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

The description provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on... prefer ask_pipeworx for casual lookups.' It also mentions the cost trade-off, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: resolver contract, parent event extraction, news fallback mechanisms, safety short-circuits on low confidence/closed markets, and resolution-rule risk. No contradiction with annotations.

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

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

The description is long but well-structured, starting with purpose, then classifiers, fan-out examples, response shapes, and safety details. Each section earns its place, though some repetition (e.g., fan-out examples) could be consolidated. Still, it is appropriately sized for the tool's complexity.

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

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

Despite no output schema, the description thoroughly explains return fields: market carries bid/ask/liquidity, analysis includes model probability and edge warnings, evidence is keyed by source, and resolver contract details match confidence and suggestions. It covers edge cases like closed markets, low confidence, and wide spreads.

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 adds value beyond the schema by providing examples, explaining depth options (quick vs thorough) with default behavior, and detailing include_raw effect (summary vs full payloads).

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 'Research a Polymarket bet' with a specific verb and resource, and distinguishes from sibling tools by detailing the fan-out and evidence packet approach. It uses concrete language about resolving markets, classifying bets, and returning 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?

Provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also includes when to inspect market_match_confidence and discusses safety short-circuits, giving clear directives for agent behavior.

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

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

The description adds significant behavioral context beyond annotations, including data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return of paired data with citation URIs. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so 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 front-loaded with example queries that quickly convey the tool's purpose, followed by essential details. While somewhat verbose, every sentence adds value (data sources, handling, output format) and there is no redundancy. It could be slightly shorter but 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?

Given the tool has only two required parameters with full schema descriptions and no output schema, the description is comprehensive. It covers when to use the tool, what data is retrieved for each entity type, how results are sorted, and what output format to expect, fully enabling an AI 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 has 100% coverage with descriptions for both parameters. The description adds value by providing examples ('AAPL', 'MSFT' for type=company; 'ozempic', 'mounjaro' for type=drug) and clarifying that values can be tickers/CIKs for companies or names for drugs, which aids the agent in parameter selection.

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

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

The description clearly states the tool performs 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and provides example queries like 'Compare X and Y' and 'rank these companies'. It distinguishes itself from sibling tools by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and mentioning alternatives like entity_profile for single entities.

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

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

The description gives explicit guidance to prefer this tool over sequential lookups for comparisons, and provides a list of example queries that indicate when to use it (e.g., 'which is bigger', 'head to head'). It does not explicitly state when not to use it, but the context of 2–5 entities and comparison is clear.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, but description adds rich behavioral context: the tool decomposes questions, uses parallel routing across 3,751 tools, returns structured findings with citations, gaps array, and explicitly states it never invents facts. 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 clear and front-loaded, but it is somewhat lengthy. Every sentence adds value, but it could be tightened slightly. For example, the account requirement could be more concise. Still, very effective.

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

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

Despite having no output schema, the description thoroughly explains the return value ('structured findings packet… with verbatim evidence, confidence, source, fetched_at, citations, gaps'). It covers prerequisites, timing, and scope. For a complex tool, this is complete.

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

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

Schema coverage is 100%, so the description is not burdened to document parameters. However, the description adds useful context: it explains the meaning of the 'depth' values (quick=3, standard=5, thorough=8) and that 'question' can be broad/multi-part. This goes slightly beyond the schema's own descriptions.

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

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

The description uses specific verbs ('decomposes', 'routes', 'extracts') and clearly states the resource ('multi-source research in one call'). It immediately distinguishes itself from sibling tool ask_pipeworx by contrasting use cases.

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

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

Explicitly says when to use this tool ('broad or multi-part questions') and when to use an alternative ('use ask_pipeworx for single lookups'). Also mentions prerequisites (Pipeworx account, paid plan for thorough depth).

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds beyond that by stating returns include full input schemas with curated examples, no second schema lookup needed, and results are ready to call directly. No contradiction with annotations.

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

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

Description is moderately long but well-structured: first sentence states purpose, then lists domains, explains return format, and gives usage guidance. Front-loaded with key info. Could be slightly more concise but overall effective.

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

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

Given no output schema, description fully explains what is returned: top-N tools with names, descriptions, full input schemas with examples. Also mentions it's for browsing and ready to call directly. Covers all essential context for the tool's use.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add parameter semantics beyond what's in schema, though it aligns with schema's examples. Adequate but no extra value.

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

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

Description clearly states the tool finds tools by describing the data or task, lists many domains, and explains it returns top-N relevant tools with full schemas. It distinguishes from sibling tools by saying 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a long list of domains. Also provides guidance to call this 'FIRST' when many tools are available, which differentiates it from specific task tools.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, but the description adds significant behavioral context: it fans across multiple sources, mentions the USPTO PatentsView API sunset (soft-fail), GDELT→GNews fallback, and the specific return fields. 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 slightly long but front-loaded with example queries and packed with information. Every sentence serves a purpose, explaining sources, fallbacks, and data fields. Could be tightened but remains effective.

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

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

Given the tool's complexity (multiple data sources, fallback mechanisms, and no output schema), the description is remarkably complete. It lists all return fields, explains the patents soft-fail, and clarifies the input format, leaving no critical gaps for an agent to misuse the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the value parameter expects a ticker or zero-padded CIK (not names) and that type is restricted to 'company'. It also provides context that names require a prior resolve_entity call.

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 creates a 'full cross-source profile of a US public company in ONE parallel call' and enumerates the data sources and fields returned, leaving no ambiguity. It distinguishes itself from siblings like resolve_entity (name resolution) and compare_entities.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It further states that names are not supported and advises using resolve_entity first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds the list of returned metrics, which is helpful but does not contradict annotations and adds limited behavioral context beyond what is already provided by annotations.

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

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

One sentence, efficient but too brief. Missing key info like that account_id is not a parameter, and the metric list differs slightly from schema defaults. Could be structured better with a clearer scope.

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

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

Output schema exists, so return values are covered. However, the description does not compensate for the missing account_id in the schema, nor does it clarify the relationship with other campaign tools. Acceptable but with clear gaps.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond what is in the schema; it mentions requiring account_id (not a parameter) and lists metrics, but fields are already described. No added semantic value.

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

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

The description clearly states 'Get campaign performance metrics' and lists specific metrics (impressions, clicks, spend, CTR, CPC, conversions, ROAS), distinguishing it from sibling tools like fb_get_campaign (likely campaign details) or fb_list_campaigns (listing).

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

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

No explicit guidance on when to use this tool versus alternatives like fb_get_campaign or fb_list_campaigns. It mentions requiring account_id and campaign_id, but account_id is not in the schema, creating confusion. No exclusions or context hints are provided.

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

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

The description claims 'Requires account_id and campaign_id', but the input schema only includes 'campaign_id' and does not have 'account_id'. This contradicts the schema and annotations. Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, but the description adds little beyond them and introduces an error.

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 concise sentence. However, it contains an inaccuracy about required parameters, which undermines its effectiveness. A clear, error-free statement would score higher.

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 output schema exists, the description does not need to detail return values. However, it misses mentioning the openWorldHint ability to request arbitrary fields. The false requirement also reduces completeness. Overall adequate but not thorough.

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 vague context about returned info (budget, targeting) but also falsely requires 'account_id'. This reduces the added value and could mislead the agent.

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

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

The description clearly states the tool retrieves detailed campaign info and lists example fields (name, budget, status, schedule, targeting). It distinguishes itself from sibling tools like fb_list_campaigns by focusing on a single campaign. However, the mention of requiring 'account_id' is inaccurate, as the schema only requires 'campaign_id'.

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

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

No explicit guidance on when to use this versus alternatives. Usage is implied by the name and context (single campaign vs list/insights), but the description does not directly state to use this for detailed campaign info and other tools for listing or metrics.

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 no behavioral context beyond confirming it returns account details. With annotations covering safety, the description adds minimal value.

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

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

A single sentence with no filler. Every word is relevant and front-loaded with the action and resource.

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

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

Output schema exists, so return value explanation is not required. The description mentions key output fields and the listing nature. It could hint at authentication scope but the annotations already indicate openWorldHint. Overall adequate.

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

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

Schema coverage is 100% with descriptions for both parameters (limit and fields). The description does not add any extra meaning or syntax guidance beyond 'Returns account IDs, names, and status.' This meets the baseline for high coverage.

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

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

The description clearly states the verb 'List', the resource 'Facebook ad accounts', and the scope 'you have access to'. It also specifies the return content: 'account IDs, names, and status'. This distinguishes it from sibling tools like fb_list_campaigns or fb_campaign_insights.

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 does not explicitly state when to use this tool versus alternatives like fb_list_campaigns. It implies usage for listing all accessible ad accounts, but lacks 'when not to use' or comparative 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 read-only, idempotent, and non-destructive. Description adds that it returns specific fields, but does not mention pagination, rate limits, or other behaviors. Adds some 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?

Very concise, one sentence and an example. The example is slightly misleading due to account_id, but overall 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 annotations, the description provides adequate context. It covers basic purpose and return fields, but lacks mention of pagination or default limit behavior.

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

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

Schema coverage is 100%, so baseline is 3. Description adds return field context but also includes an example with account_id which is not a parameter, potentially misleading. No additional syntax or format details beyond schema.

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

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

Clearly states it lists ad sets in a campaign, but the example includes account_id which is not a parameter, causing minor confusion. Distinguishes from sibling fb_list_campaigns implicitly but not explicitly.

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

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

No guidance on when to use this tool versus alternatives (e.g., fb_list_campaigns). Only implicit requirement of a campaign_id. No exclusions or alternative suggestions.

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, and idempotentHint, so the description doesn't need to reiterate safety. It adds that the tool returns specific fields but lacks details on pagination, rate limits, or behavior with 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?

Extremely concise: one sentence plus a parenthetical example. Every word contributes to understanding the tool's function and return data.

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 an output schema (though not shown), the description covers return fields minimally. It omits pagination, error handling, and field selection guidance, but is acceptable for a simple list 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 baseline is 3. The description provides an example and hints at the account_id format, but doesn't add meaning beyond the schema's parameter descriptions.

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

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

The description clearly states it lists campaigns in a Facebook ad account and specifies the return fields (names, IDs, status, objectives). It implicitly differentiates from siblings like fb_get_campaign (single) and fb_campaign_insights (metrics), but could explicitly contrast them.

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

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

No guidance on when to use this tool versus alternatives such as fb_campaign_insights or fb_get_campaign. The example shows basic usage but omits context like when listing all campaigns is appropriate or when filtering is needed.

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

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

Annotations already declare destructiveHint: true, so the description aligns. It adds specificity by stating 'memory by key' but does not elaborate on side effects or permissions, which is acceptable given the annotation coverage.

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

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

The description is two sentences, front-loaded with the action and conditional usage, with no superfluous 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?

For a simple deletion tool with one parameter and no output schema, the description covers purpose, usage, and sibling context. It lacks explicit mention of return behavior or error handling, but overall it 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?

The schema coverage is 100%, and the description does not add meaning beyond the schema's parameter description 'Memory key to delete'. The schema already provides an example, so the description meets the baseline but adds no extra 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 the verb 'Delete' and resource 'memory by key', distinguishing it from siblings like remember and recall by explicitly pairing with them.

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

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

The description provides explicit when-to-use scenarios: stale context, done task, or clearing sensitive data. It also mentions pairing with remember and recall, giving alternatives.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds contextual behavior: fetches page, extracts title/description/key links, emits standard markdown. This is consistent and adds value beyond annotations 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?

Description is three sentences, front-loaded with the primary action. It avoids redundancy, though the use cases could be slightly more concise. Overall efficient and well-structured.

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

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

Given the simple tool (2 params, no output schema, rich annotations), the description adequately covers purpose, process, and use cases. It mentions the output format ('single text blob') but omits error handling or URL validation details. Still, it is sufficient for an AI agent to understand the tool's function.

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

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

Schema description coverage is 100% for both 'url' and 'max_links'. The description reiterates the URL purpose and mentions default/max for max_links, but does not add new semantic information beyond the schema. 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?

Description clearly states what the tool does: 'Generate a production-ready llms.txt file for any URL'. It specifies the verb ('generate'), resource ('llms.txt file'), and purpose ('for AI crawlers to index the site cleanly'). It distinguishes from siblings like 'ai_visibility_check' and 'scan_competitor_ai_presence' by focusing solely on file generation.

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 three explicit use cases (client site indexing, personal project, competitor auditing), which is helpful. However, it does not mention when not to use this tool or compare with sibling tools that might overlap (e.g., 'ai_visibility_check' or 'scan_competitor_ai_presence'). Missing explicit alternatives or 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, idempotentHint, destructiveHint, openWorldHint. Description adds the default filtering behavior (active subscriptions) and lists return fields, providing transparency beyond annotations.

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

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

Two sentences, front-loaded with purpose, 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?

Despite no output schema, description lists return fields. Provides usage guidance and parameter context. Fully adequate for a simple list 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 the parameter already described. Description adds value by implying when to use the include_inactive parameter (e.g., for cancellation context).

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

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

Description clearly states it lists the caller's active subscriptions, specifies return fields (id, type, params, created_at, last_fired_at, fire_count), and distinguishes from siblings like subscribe/unsubscribe by focusing on review and cancellation.

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

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

Description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't explicitly name alternatives, the context and sibling tools make it clear when to use this tool.

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

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

Annotations are minimal (all false), but the description adds key behavioral traits: 'Rate-limited to 5 per identifier per day. Free; doesn't count against your tool-call quota.' This goes beyond what annotations provide.

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

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

Description is a single paragraph but well-structured: starts with purpose, then usage scenarios, then formatting instructions, then constraints. No unnecessary words; 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 feedback tool with 3 parameters and no output schema, the description covers all necessary aspects: what to send, how to send it, and constraints (rate limit, free). No gaps.

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

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

Schema coverage is 100% (all parameters have descriptions). The tool description reinforces and clarifies enum meanings (e.g., 'praise = positive note') and provides context for the 'context' object. Adds marginal 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?

Clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist' and lists specific categories (bug, feature/data gap, praise). Distinguishes from sibling tools, which are mostly query or research tools.

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

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

Explicitly describes when to use: 'when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked well (praise).' Also provides instructions on how to structure feedback and notes rate limits and quota exemption.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This informs the agent about data freshness and privacy.

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 extremely concise—three sentences plus a bulleted list—with every sentence adding value. It is front-loaded with the core purpose and structured for quick reading.

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 trending tool with no output schema, the description covers all essential aspects: what is returned (top tools, packs, call volume), window options, caching behavior, and use cases. It is complete and leaves no obvious gaps.

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

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

The input schema already fully describes the single parameter (window) with its enum and description. The tool description reinforces this but does not add new semantic information beyond the schema, meeting the baseline for high 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's purpose: 'Returns the top tools, top packs, and total call volume' over a recent window, with specific use cases. It distinguishes itself from siblings like 'discover_tools' by focusing on trending based on other agents' calls.

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

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

The description provides three specific use cases (discovering hot data sources, confirming canonical tools, aligning use cases), offering clear guidance on when to use the tool. However, it does not explicitly mention when not to use or compare with alternatives.

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

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

Despite annotations already marking readOnlyHint, openWorldHint, idempotentHint, the description adds rich behavioral context: exactly one of event/topic required, internal checks (monotonicity, partition sum, Jaccard similarity, placeholder filtering), fill check against CLOB depth, and output structure. It fully discloses behavior beyond annotations, earning a 5.

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

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

The description is well-structured and front-loads the key requirement (REQUIRES one of event or topic). Every sentence adds value, but it is quite long. Given the tool's complexity, the length is justified, but slightly more conciseness could help. Score 4.

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

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

Even without an output schema, the description fully explains the response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context), partition_check (sum_yes_prices, gap_from_1, etc.), and fill check details. It covers error cases like placeholder filtering and skipped low similarity. It also directs to polymarket_fill_risk for custom sizing. Complete for agent use.

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

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

Schema has 100% coverage with descriptions for both event and topic. However, the tool description adds crucial meaning: event takes a slug like 'fed-decision-may-2026' (full URLs accepted), topic takes a seed question like 'Fed rate decision', and explains how each mode works internally (walking child markets, scanning across events). This goes far beyond schema basics, earning a 5.

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 on Polymarket via monotonicity violations and partition-sum checks. It distinguishes event mode (specific market) from topic mode (cross-event scanning), providing concrete examples like 'fed-decision-may-2026' and seeds like 'Fed rate decision'. This specificity and differentiation from sibling tools (e.g., polymarket_edges, polymarket_fill_risk) earns a 5.

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

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

The description explicitly tells when to use each mode: 'event (recommended for a specific market)' and 'topic (for cross-event scanning)'. It warns that calling with no args fails. It explains that cross-event mode catches patterns single-event misses and references polymarket_fill_risk for custom sizing. This full guidance earns a 5.

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

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

The description discloses extensive behavioral traits beyond annotations: three model families with detailed methodology, caching behavior (1h KV cache keyed on knobs), edge calculations (net of slippage, Kelly fraction caps), Fed bet handling (excluded from ranking), and diagnostic information for empty segments. All details align with readOnlyHint and idempotentHint.

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

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

The description is front-loaded with purpose and well-organized into sections (model families, knobs, response, caching). However, it is verbose and could be shortened without losing clarity. Every sentence adds necessary detail for a complex tool, but conciseness is slightly compromised.

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

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

Given the complexity (9 parameters, multiple model families, diagnostic output), the description fully covers what a caller needs: response structure, edge cases (placeholder-slug filter, Fed note), caching, and why segments might be empty. Without an output schema, the description compensates by detailing top-level fields and diagnostics.

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

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

Schema coverage is 100% with clear descriptions, so baseline is 3. The description adds value by explaining parameter interactions (e.g., min_kelly does not filter partition arbs, min_partition_leg_kelly applies per-leg) and providing usage guidance on values (e.g., slippage_pp default rationale). This exceeds baseline.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It specifies the intended use case ('what should I bet on today') and distinguishes from related tools by focusing on pipeworx disagreement. The verb 'scan' and resource 'top Polymarket markets' are specific and actionable.

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

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

The description provides clear context for when to use the tool ('what should I bet on today') and hints at its advantage (no paging hundreds of markets). However, it does not explicitly list alternatives or state when not to use it, leaving some ambiguity among sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description adds significant behavioral context beyond the annotations: it explains the snapshot-based approach, the structure of tracked/expired/snapshot_dates responses, that decay is computed from daily closes (not intraday), and limitations like 60-day TTL. This enriches the agent's understanding without contradicting the read-only, 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 fairly long but well-organized: it starts with the core purpose, then explains response structure, and ends with limitations. Every sentence adds value, though minor trimming could improve conciseness. Overall, it is effectively structured and informative.

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

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

Given no output schema, the description fully explains the return value structure (tracked[], expired[], snapshot_dates[]) and includes limitations (60-day TTL, snapshot gaps). This is complete for a tool performing time-series analysis on snapshots.

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

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

Schema coverage is 100%, so the description's parameter details (defaults, ranges) largely mirror the schema. It adds context about their role in snapshot lookback and family selection, but does not provide new semantic meaning beyond what the schema offers. Baseline 3 is appropriate.

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

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

The description clearly states it provides edge persistence and decay telemetry, answering a specific question about edge duration. It distinguishes itself from the sibling tool polymarket_edges, which likely provides current edge data, by focusing on historical snapshots and trends.

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: to assess whether an edge is fresh or stale, with a concrete example contrasting a new wide edge versus a three-week-old one. It does not explicitly list alternatives but implicates polymarket_edges as the tool for current edges, providing clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: walks the ladder, returns detailed fields, warns about partial fills and directional risk. This exceeds the baseline but is not critically additional beyond what annotations convey.

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

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

The description is long but well-structured with bold section headers (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It front-loads core purpose. Slightly verbose, but the structure aids readability.

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

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

Given the tool's complexity (two modes, many return fields) and no output schema, the description fully explains what is returned for each mode, including specific fields and the purpose of the check. Usage context and warnings are thorough.

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

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

Schema coverage is 100%, so baseline 3. The description adds extra meaning: side defaults differ per mode, size_usd interpretation differs for single vs basket, lists defaults and constraints. 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 checks realizable vs theoretical edge against live CLOB order-book depth. It specifies two modes (single-market and basket) and distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a pre-action check.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns against thin books and partial fill risks, providing clear when-to-use and what happens otherwise.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds extensive behavioral context beyond these: it explains the spread calculation, safety fields (compatibility_warning, temporal_alignment, skipped counters), and limitations (e.g., temporal mismatch, non-equivalent bet shapes). No contradictions.

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

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

The description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bullet-like lists. It is somewhat verbose, but every sentence adds necessary detail for a complex tool. Could be tightened slightly, but still appropriately concise given the tool's complexity.

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

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

Given the tool's complexity (two modes, multiple safety fields, temporal alignment) and the absence of an output schema, the description completely covers return values (leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and explains their interpretation. No gaps remain.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the behavior (e.g., 'auto-fetch matching event', 'overrides the topic-mapped side') and listing valid values for 'topic'. This goes beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('Cross-venue spread') and resource ('Polymarket-Kalshi Spread'), and distinguishes from siblings like polymarket_arbitrage and polymarket_edges by being a dedicated spread tool.

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

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

The description explicitly outlines two modes ('topic' for pre-mapped macros, 'explicit' for custom pairings) and provides guidance on when to use each. It also warns that most pre-mapped topics return a compatibility_warning, indicating tradeability is limited, which helps the agent decide when not to use the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint; description adds scoping to identifier and pairing with remember/forget, no contradiction.

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

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

Two sentences, front-loaded with core purpose, each 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?

Simple tool with one param and no output schema; description covers behavior, scope, related tools, and use cases comprehensively.

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

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

Schema documents the single optional 'key' parameter fully (100% coverage); description adds nuance that omitting key lists all saved keys.

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

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

Description states verb 'retrieve' and resource 'value saved via remember' or list keys; distinguishes 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?

Explicitly says to use for looking up context stored earlier and mentions scoping; lacks explicit when-not-to-use but pairs with forget and remember.

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

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

Discloses that mark_read:true flags events as read, which is a state change. Adds context about the persisted feed and direct URL, complementing annotations (readOnlyHint, idempotentHint). No contradictions.

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

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

Four concise sentences, front-loaded with purpose, each adding relevant detail 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?

Covers all key aspects: what alerts contain, filtering, mark_read behavior, polling suitability, and alternative direct endpoint. No output schema needed as description covers returns.

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?

Adds value beyond the 100% schema coverage by giving a concrete type example ('sec_8k'), clarifying 'since' semantics (fired_at >= time), and explaining mark_read and unread_only behaviors.

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 pulls fired events from a subscription feed and returns recent alerts with key fields, distinguishing it from sibling tools like 'list_subscriptions' and 'subscribe'.

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 examples of filtering by type and since, explains mark_read effect, mentions polling works fine, and notes an alternative API endpoint. Lacks explicit exclusions or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a safe profile. The description adds rich behavioral details: fan-out logic, fallback from GDELT to GNews, USPTO soft-fail, return structure with grouped changes and citation URIs. No contradiction with annotations.

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

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

The description is a single paragraph, but it is well-structured with examples and logical flow. It is somewhat long but each sentence contributes meaning. Slightly more conciseness could be achieved, but overall effective.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats), the description covers all essential aspects: sources, parameter options, return structure, and limitations (e.g., USPTO soft-fail). No output schema, but the description mentions the return shape sufficiently.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the `since` parameter format (ISO date or relative shorthand) with examples, clarifies the `type` is only 'company', and expands on `value` as ticker or CIK. This extra context 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 provides a change feed for a company over a time window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It gives concrete example queries like "What's new with X" and distinguishes itself from the sibling tool entity_profile, which is for static profiles.

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

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

The description explicitly tells when to use the tool (for recent changes) and when not to (use entity_profile for static profile). It provides context on the window parameter and suggests typical usage like "30d" for monitoring.

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 idempotent and non-destructive behavior. The description adds valuable context about persistence duration (24 hours for anonymous) and scoping by user identifier. No contradiction with annotations.

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

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

The description is a single paragraph of 5 sentences, front-loaded with purpose, then usage, then details. No superfluous information.

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

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

For a simple memory save tool, the description is fairly complete. It does not mention return values, but output schema is absent. It references sibling tools recall and forget, providing good context.

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

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

The input schema has 100% coverage with descriptions for key and value. The description adds context that values are arbitrary text and memory is scoped, which adds some meaning beyond the schema.

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

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

The description clearly states the verb 'save' and the resource 'data (key-value pair)'. It distinguishes from siblings by explicitly pairing with recall and forget.

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

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

The description provides clear guidance on when to use ('when you discover something worth carrying forward') and gives examples. It does not explicitly state when not to use, but the context of pairing with recall/forget implies alternatives.

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

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

Annotations already mark the tool as readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with example queries and a clear imperative ('Use FIRST'). It is mostly concise but includes some repetitive phrasing (e.g., 'auto-disambiguated' could be trimmed). Overall, it is well-structured and efficiently communicates key 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?

Given no output schema, the description thoroughly explains return values for each entity type, including citation URIs. It also notes internal cascading behavior. For a tool with only two simple parameters, this is complete and leaves no ambiguity about what the tool does or returns.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining what each type returns (e.g., for company: ticker, CIK, company_name, URI; for drug: RxCUI, ingredient, brand, URI). It provides input examples (AAPL, 0000320193, ozempic) that clarify accepted formats and 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 resolves a user-spoken name to a canonical/official identifier for entity types like company and drug. It provides concrete examples (ticker, CIK, RxCUI) and distinguishes itself from siblings by specifying that it returns identifiers required by other tools. The verb 'resolve' and resource 'entity' are explicit and unambiguous.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing clear context for when to employ this tool. It lists supported types with examples but does not explicitly state when not to use it or mention alternative tools. Given the sibling list, no other tool directly competes, so the guidance is strong but lacks exclusion criteria.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds that it probes each entity with ai_visibility_check, returns a ranked list with score, confidence, and signal density. This provides useful behavioral detail beyond annotations without contradiction.

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

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

The description is two concise sentences plus a parenthetical example. It front-loads the main purpose and uses every word efficiently. No redundant or vague phrasing.

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

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

With no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers the probing process and entity roles. Minor gap: could mention maximum entities more explicitly, but '2-8' is given.

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

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

Schema coverage is 100%, but the description adds valuable context: explains that 'models' supports 'workers-ai' (default) and 'anthropic' (requires _apiKey), clarifies that _apiKey is optional, and gives an example for 'context'. This significantly enhances understanding beyond the schema alone.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling tool 'ai_visibility_check' by emphasizing side-by-side comparison and ranking.

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

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

The description explicitly states the use case ('competitive AI-marketing audits') and provides an example question. It implies that for a single entity, one should use ai_visibility_check, though it does not explicitly name that alternative. Guidance on entity count (2-8) and first entry as subject 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?

Adds substantial context beyond annotations: describes composite nature, partial failure handling, potential timeouts (5-30s), and specific return fields. No contradictions with 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?

Well-structured and front-loaded with key info. While verbose, every sentence adds value. Could be slightly more concise, but overall effective.

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

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

Despite no output schema, the description thoroughly details return fields (summary block, advisories, links, alternative versions) and handles edge cases like partial failures and delays. Fully adequate for agent use.

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

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

Input schema covers all parameters with full descriptions, so baseline is 3. Description adds minor value by mentioning scoped packages are accepted, but does not significantly enhance understanding beyond schema.

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

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

The description clearly states the tool's purpose as a composite check for npm packages, covering license, advisories, bundle size, etc. It uses specific verbs like 'scan' and 'check', and effectively distinguishes itself from siblings by focusing on dependency analysis.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, or size of an npm package. Also clarifies scope limitations (NPM only in v1) and directs to deps.dev for other ecosystems, providing clear alternatives.

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

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

The description adds significant behavioral details beyond annotations: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation flag, and passage offsets for verification. 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?

Extremely concise: two sentences that front-load purpose, then usage, then technical details. Every sentence adds value.

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

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

Despite no output schema, the description fully covers what is returned (passages with offsets and scores), the embedding model, window size, and cap behavior. Complete for a semantic search tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete examples for 'query' (e.g., 'supply-chain risk') and reiterating constraints for 'text' and 'limit' with clarity.

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

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

The description clearly states it is a semantic search inside a fetched record, with specific examples (SEC 10-K body, article) and output details (passages with offsets and similarity scores). It explicitly pairs with a sibling tool, distinguishing itself.

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 when-to-use guidance ('Use when the record is too big to cram into the prompt') and mentions pairing with ask_pipeworx_grounded. It does not explicitly state when not to use it, but the context is sufficient.

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

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

The description discloses behavioral traits beyond annotations: authentication requirements (OAuth account), mutation (creation), idempotent creation, non-destructive nature, delivery constraints (email verification, SMS cap, webhook auto-disable), and the always-on feed. 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 well-structured, starting with purpose, then requirements, supported types, and delivery. It is moderately concise; every sentence adds value, though it could be slightly more compact without losing clarity.

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

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

Given the tool's complexity (multiple types, delivery options, auth requirements) and no output schema, the description covers authentication, type parameters, delivery constraints, and response. It is highly complete for an agent to correctly invoke the 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?

The schema already provides detailed descriptions for type, params, and delivery. The description adds further context such as specific examples for each type and webhook signing secret details, enhancing semantics without redundancy.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description implicitly conveys when to use by stating it requires an OAuth account and specifying supported types and delivery channels. It does not explicitly compare to alternatives but provides enough context for an agent to infer correct usage.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context: it is stateless, returns suggestions based on the live catalog, and has no side effects, fully disclosing behavior.

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

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

The description is somewhat long due to listing synonyms and examples, but it is well-structured and front-loaded with the core functionality. Every sentence adds value, though slight trimming could improve conciseness.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all needed information: what it returns, when to use it, and how to customize. No gaps remain.

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

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

Schema coverage is 100% with a good description for 'topic'. The description adds extra meaning by explaining that omitting 'topic' gives a 'cross-category spread' and focusing narrows results, which goes beyond the schema.

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

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

The description uses specific verbs like 'returns category-bucketed example questions' and clearly identifies the tool as the onboarding entry point, distinguishing it from siblings like 'discover_tools' or 'ask_pipeworx'.

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

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

Explicitly states to use this tool 'FIRST when you do not yet know what Pipeworx can do for you' and explains the optional 'topic' parameter for focused use, providing clear context and alternatives.

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

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

Adds critical behavioral context beyond annotations: ownership enforcement, deactivation (not deletion), and historical availability via recent_alerts. Annotations already indicate idempotent and non-destructive, and description aligns perfectly.

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 short sentences, front-loaded with main action, every sentence adds value. No fluff or repetition.

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

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

For a single-parameter tool with good annotations, the description fully covers purpose, constraints, side effects, and linkage to sibling tools (recent_alerts). No output schema needed.

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 has 100% coverage with id description. Description does not add further parameter-level detail beyond confirming usage by id. Baseline score of 3 is appropriate.

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

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

Clearly states the action ('Cancel a subscription by id') and resource. Distinct from sibling tools like subscribe and list_subscriptions, with additional details about ownership and deactivation semantics.

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: ownership enforcement (only own subscriptions) and deactivation behavior (history accessible via recent_alerts). Lacks explicit when-not-to-use or direct alternative naming, but sufficient for a simple tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: returns a verdict, extracted structured form, actual value with citation, and percent delta. Also notes it supports v1 company-financial claims via SEC EDGAR + XBRL. No contradictions. 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?

Description is front-loaded with example queries and a clear usage statement. Each sentence adds information: use case, scope, return format. Slightly long but not wasteful. Structured logically.

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 single parameter and no output schema, the description covers what the tool does, the supported claim types, and the return format. It mentions the verdict list, citation, and percent delta. Could include an example of a refuted claim but still complete enough 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 has 100% coverage for the single parameter 'claim' with clear description. The tool description adds synonyms and usage patterns (e.g., 'Is it true that...'), and provides context on what types of claims are supported. This enhances the schema description.

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

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

Clearly states it performs natural-language claim verification against authoritative sources. Provides specific examples like 'Is it true that...' and explicitly distinguishes itself from siblings by noting it replaces 4-6 sequential calls. The verb+resource+scope is well-defined.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Defines scope to company-financial claims. Does not explicitly state when not to use, but the scope implies limitations. Missing mention of alternatives, but the scope is clear enough.

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