Facebook_ads

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

Annotations already declare readOnlyHint=true, openWorldHint, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: the default model (Workers AI Llama-3.3-70b), the cost implication for Anthropic (BYO key), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradictions.

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

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

Three sentences, all essential. First sentence states purpose and output format. Second sentence adds default and API key details. Third sentence covers return structure and use cases. No redundancy, front-loaded.

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

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

Given 4 parameters, no output schema, the description covers the return format partially (per-model fields) and the cost model. It lacks details on scoring scale, rate limits, or error handling, but these are minor for a read-only probe tool. Use cases and disambiguation feature are well explained.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning: 'entity' is defined as 'The thing to ask about' with examples; 'models' lists supported options and notes omission behavior; '_apiKey' clarifies direct pass-through to Anthropic; 'context' explains disambiguation purpose. 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 verb 'probe', the resource 'LLMs', and the output 'visibility score (0-100) per model'. It covers scope (business/brand/product/topic). However, it does not explicitly distinguish from siblings like 'entity_profile' or 'scan_competitor_ai_presence', which could lead to ambiguity.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the free default model versus BYO key for Anthropic. It lacks explicit when-not-to-use guidance or comparison to sibling tools, but the context is clear overall.

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?

No annotations are provided, so the description must disclose behavior. It explains that the tool 'picks the right tool, fills the arguments' and returns the result, but it does not clarify any side effects, rate limits, or limitations (e.g., what if no tool matches). This is adequate but not comprehensive.

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 at two sentences plus examples, with no wasted words. It is front-loaded with the core purpose and immediately gives actionable examples.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is largely complete. It explains the tool's role as an orchestrator, which is sufficient for an AI agent to understand when to invoke it. Could be improved by noting what happens when no suitable tool is found.

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

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

The input schema has 100% description coverage for its single parameter, so the description adds minimal value beyond what the schema already states. The schema already describes 'question' as 'Your question or request in natural language', which the description echoes. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool takes a plain English question and returns an answer by picking the right tool and filling arguments. It provides concrete examples, distinguishing it from sibling tools that likely require structured queries.

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

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

The description explicitly says to 'just describe what you need' and provides usage examples, implying the tool handles diverse queries. It does not explicitly state when not to use it, but the examples and context suggest it replaces the need to browse other tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by explaining the internal logic: resolves market, classifies bet, fans out to relevant packs, and returns a comparison. No contradictions.

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

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

The description is a single paragraph that front-loads purpose and input types. It is informative without being overly verbose, though it could be slightly more structured.

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

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

Given the tool's complexity (13 siblings, no output schema), the description covers purpose, inputs, internal process, and output. It lacks error handling or cost details, but overall provides sufficient context 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 coverage is 100%, baseline 3. The description adds that `market` can be a slug, URL, or question text, and explains the `depth` enum values ('quick' vs 'thorough') with context on what they mean.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from siblings by branding it as the core demo product.

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 use cases ('should I bet on X?', 'what does data say?', 'is there edge?') and contrasts with the need to discover packs manually. It does not explicitly state when not to use, but the usage is well-scoped.

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?

No annotations provided, so description carries full burden. It states it returns paired data and URIs, and replaces multiple calls. No side effects or destructive behavior are indicated, which seems appropriate for a read-like operation, but more detail on output structure would improve transparency.

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

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

Three concise sentences. First sentence states core purpose, second details types, third summarizes return and efficiency. No redundant words. Front-loaded with the main compare action.

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

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

Given no output schema, the description mentions return includes 'paired data' and URIs, but does not specify the format or structure. Also missing prerequisites like data source access (SEC for companies). Adequate but could be more 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 is 3. The description adds value by explaining the 'type' enum with examples and mapping to specific metrics for company vs drug. It also provides concrete examples for 'values'. This goes 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?

Description clearly states the tool's purpose: comparing 2–5 entities. It specifies two entity types and the metrics returned. However, it does not explicitly differentiate from sibling tools, though the context suggests uniqueness.

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. Sibling tools like ask_pipeworx or the fb_* tools are not mentioned. The description implies it's for multi-entity comparison but lacks explicit usage constraints.

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?

No annotations provided, so description carries full burden. It discloses that it searches a catalog and returns tools with names and descriptions, but does not mention pagination, ranking details, or potential rate limits. However, for a search tool, this is sufficient.

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

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

Two sentences, front-loaded with the action, minimal waste. Every sentence adds value.

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

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

Given low complexity (2 parameters, no nested objects, no output schema), the description is complete enough. It explains the tool's purpose and when to use it. Could add example queries or mention that it returns tool names and descriptions, but not necessary.

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

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

Schema coverage is 100% and both parameters are well-described in the schema. The description does not add additional meaning beyond the schema, but baseline is 3 given 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 searches a tool catalog by describing what you need, and returns the most relevant tools. It is distinct from siblings which are specific actions (like fb_list_campaigns) or memory operations (forget, recall).

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

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

The description explicitly tells when to use: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This provides clear context and prioritization.

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?

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only operation and describes the output format (citation URIs), but does not cover error conditions, rate limits, or idempotency. Adequate but lacks depth.

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, front-loaded with the core purpose, and every sentence adds value. No redundancy or fluff.

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

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

Given the lack of an output schema, the description provides substantial context about what data is returned (SEC filings, revenue, patents, etc.). It could mention if the response is paginated or rate-limited, but for a profile tool, it is sufficiently complete.

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

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

The input schema has 100% coverage, and the description adds meaning beyond the schema: it explains that 'value' accepts ticker or CIK (not names) and that 'type' currently only supports 'company'. This helps the agent invoke the tool correctly.

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

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

The description clearly states it returns a full profile of an entity across multiple packs, listing specific data sources (SEC filings, XBRL, patents, contracts, news, LEI). It distinguishes itself from siblings like 'resolve_entity' by noting prerequisites.

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 it (comprehensive profile in one call), mentions an alternative ('resolve_entity' for names), and emphasizes efficiency (replaces 15-30 calls). It could mention when not to use it relative to 'compare_entities', but overall provides good 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 are empty, so description carries full burden. It mentions metrics but not behavioral traits like rate limits, data freshness, or pagination. Adequate but not comprehensive.

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 short sentence is efficient, but could be slightly more front-loaded with the main action. No wasted words.

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

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

Given 5 params, no output schema, and no annotations, description is adequate but lacks guidance on return format, filtering options, or performance limits.

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 no extra meaning beyond 'get insights', but schema already documents parameters well.

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 retrieves performance metrics (impressions, clicks, spend) for a campaign, distinguishing it from sibling tools like fb_get_campaign (likely details) and 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?

Description implies usage for insights but does not explicitly compare to alternatives (e.g., when to use this vs fb_get_campaign). No guidance on prerequisites or 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?

No annotations are present, so the description carries full burden. It states the tool 'gets details', which implies a read-only operation. However, it does not disclose any behavioral traits like potential rate limits, authentication requirements, or what happens if the campaign_id is invalid.

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 that front-loads the core purpose. Every word adds value, with no fluff.

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

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

Given the tool has 2 parameters with 100% schema coverage, no output schema, and no annotations, the description is minimally complete. It could be improved by noting the return format (e.g., JSON object) or mentioning that it requires a valid campaign_id.

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

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

Schema coverage is 100% and already describes both parameters (campaign_id, fields). The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves details for a specific Facebook Ads campaign, using the verb 'get' and identifying the resource as 'campaign'. It distinguishes from siblings like fb_list_campaigns (which lists) and fb_campaign_insights (which provides analytics).

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

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

The description implies when to use (when you need details for one specific campaign), but provides no explicit guidance on when not to use it or mention of alternatives among siblings.

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

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

No annotations are provided, so the description carries the full burden. It only states the basic function, not disclosing behaviors like pagination, rate limits, or auth requirements. The tool accesses live Facebook data, but no caution is given.

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, focused sentence that states exactly what the tool does with no extraneous words. Perfectly concise.

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

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

Given no output schema, the description should hint at return format or behavior. It is adequate for a simple listing tool with well-documented parameters, but lacks info on pagination or common defaults. It is minimally complete.

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

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

Schema description coverage is 100% with clear descriptions for both parameters. The description adds no extra param info, but baseline is 3 and the description's scope statement ('ad accounts accessible by...') provides context that the schema lacks, earning 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 verb 'List' and the resource 'ad accounts', specifying the scope 'accessible by the authenticated Facebook user'. This is distinct from sibling tools which focus on campaigns, adsets, or 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 implies a simple listing action with no usage guidance or alternatives. It doesn't mention when to use this vs. other listing tools, but the tool name and description make its purpose clear relative to siblings.

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

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

No annotations are provided, so the description carries full burden for behavioral transparency. The description only states 'list ad sets', giving no information about side effects, authentication requirements, rate limits, or result ordering. For a listing operation, it lacks details on pagination behavior beyond the limit parameter.

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

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

The description is a single sentence that is concise and front-loaded. It avoids unnecessary words and gets to the point quickly. No waste.

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

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

Given the tool's simplicity (3 parameters, 1 required, no nested objects), the description covers the basic purpose. However, it lacks details on the return format, sorting, or handling of invalid campaign IDs. The tool is straightforward, so a 3 is adequate.

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

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

Schema description coverage is 100%, with each parameter having a description in the schema. The description adds no additional meaning beyond the schema's parameter descriptions, achieving the baseline score of 3.

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

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

The description clearly states the tool lists ad sets for a specific campaign, using the verb 'list' and the resource 'ad sets' with the qualifying context 'for a specific campaign'. This distinguishes it from siblings like fb_list_campaigns and fb_get_campaign.

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

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

The description implies usage when you have a campaign_id and need to list its ad sets, but does not explicitly state when to use it versus alternatives. No guidance on when not to use or prerequisites beyond the required campaign_id.

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 empty, so the description carries the full burden. It discloses that it lists campaigns, but does not mention rate limits, pagination behavior, or what happens if the account ID is invalid. It states the default limit, which is helpful, but lacks mutation warnings (it is read-only, but not stated).

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

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

Single sentence, front-loaded with purpose. Efficient and no redundant information. However, it could be slightly improved by including a note about pagination or defaults in the same sentence.

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 low complexity (3 params, no output schema), the description covers the basics but lacks context about return format, pagination, and error handling. With no output schema, the description should ideally mention what is returned (e.g., list of campaign objects).

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

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

Schema coverage is 100% with descriptions for each parameter (act_account_id, limit, fields). The description adds no further meaning beyond what is in the schema, so baseline score 3 is appropriate. It does not explain field syntax or provide examples 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 ('List') and resource ('campaigns') and specifies the scope ('for a Facebook ad account'), which is specific enough. It distinguishes from siblings like fb_campaign_insights and fb_get_campaign, but could more explicitly differentiate from fb_list_adsets.

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 vs alternatives such as fb_get_campaign (for a single campaign) or fb_list_adsets. The description implies it's for listing, but does not state prerequisites (e.g., need to list ad accounts first) or when not to use it.

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

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

No annotations provided, so the description must carry behavioral disclosure. It does not specify if the deletion is irreversible, whether it returns any confirmation, or if there are side effects on related data.

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 short sentence that conveys the purpose efficiently. Could be slightly more informative but no wasted words.

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

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

Given no output schema and no annotations, the description should provide more context about the operation's effects, return value, or prerequisites. It is minimally complete for a simple delete action but lacks depth.

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 the parameter. Description adds 'stored memory' context but no additional constraints or format details 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?

Description clearly states the action (Delete), resource (stored memory), and identifier (by key). It is specific and distinguishes from siblings like 'remember' (store) and 'recall' (retrieve).

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 vs alternatives. For example, it doesn't clarify if it should be used for temporary vs permanent deletion, or if there are any restrictions on keys.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, and outputs standard llms.txt markdown as a single text blob. 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 two sentences, front-loaded with the core purpose, and every sentence provides useful information. 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?

The tool has no output schema, but the description states the output is a single text blob (llms.txt format). It explains the process (fetch, extract, emit) and usage scenarios, which is sufficient for a simple tool. Could mention rate limits or error cases, but not required.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description does not add significant extra meaning beyond the schema, but it does briefly imply the output format. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'Generate' and the resource 'llms.txt file'. It distinguishes itself from unrelated siblings by explicitly mentioning the purpose for AI crawlers like ChatGPT, Claude, and Perplexity.

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

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

The description explicitly lists useful scenarios: indexing a client's site, drafting for own project, or auditing competitor visibility. While it does not mention when not to use, the context is clear and no alternative tools exist among siblings.

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

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

With no annotations provided, the description must disclose behavioral traits. It reveals the rate limit (5 per identifier per day) and a constraint on content. It does not describe what happens after submission (e.g., confirmation, response). The disclosure is adequate but not exhaustive.

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

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

The description is very concise, using two sentences to state purpose, use cases, guidelines, and rate limit. Information is front-loaded with the core purpose. No unnecessary words.

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

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

For a simple feedback tool with no output schema, the description covers purpose, usage guidelines, rate limit, and content restrictions. It could mention what the user can expect after submission (e.g., no confirmation), but overall it is sufficiently complete.

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

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

Schema coverage is 100%, so the schema already documents each parameter thoroughly. The description adds no new parameter-specific details beyond what is in the schema. The baseline of 3 is appropriate.

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

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

The description explicitly states the tool's purpose: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, missing data, praise), clearly distinguishing it from sibling tools which are for data retrieval or memory.

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 the tool (for various feedback types) and what to include ('Describe what you tried in terms of Pipeworx tools/data') and exclude ('do not include the end-user's prompt verbatim'). It also mentions the rate limit. However, it does not explicitly state when not to use it, though the use cases are comprehensive.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by disclosing the data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('cached 5min-1h'). No contradiction with annotations.

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

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

The description is concise, with no wasted words. It is well-structured: first sentence defines purpose, then lists use cases in a numbered format, followed by 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?

For a simple read-only tool with one optional parameter and no output schema, the description covers purpose, usage, and behavioral context well. It lacks explicit return field names but implies the structure ('top tools, top packs, total call volume'). Annotations provide safety context.

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

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

Schema coverage is 100% with a description for the only parameter 'window'. The description repeats the enum values but adds no deeper semantic beyond what the schema already provides. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for a recent window. It specifies the verb 'returns' and the resource 'what other AI agents are calling', differentiating it from siblings like 'discover_tools' which likely lists all 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?

Three explicit use cases are given (discovering hot data sources, confirming canonical choice, aligning with agent needs). Window selection guidance ('shorter windows surface what's hot') is provided, but no direct exclusions or alternatives to sibling tools are mentioned.

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

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

Annotations readOnlyHint, openWorldHint, destructiveHint are consistent. Description details behavior: walks child markets, extracts dates/thresholds, sorts, reports violations. Adds useful context beyond annotations.

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

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

Description is a single, dense paragraph with no wasted words. Front-loaded with purpose, followed by explanation, example, and output format. Highly 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 one parameter, no output schema, the description covers input, logic, and output format. Could specify event identification more precisely, but overall complete for the tool's scope.

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?

Only one parameter 'event' with schema description coverage 100%. Description adds behavioral context: 'Pass a Polymarket event slug or URL; the tool walks the child markets'. This enhances the schema definition.

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

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

Description clearly states 'Find arbitrage opportunities within a Polymarket event by checking for monotonicity violations'. Uses specific verbs and resources, and distinguishes from siblings by focusing on monotonicity arbitrage within a single event.

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?

Explains when to use: when an event has multiple related markets with different dates/thresholds. Provides a concrete example of monotonicity. Does not explicitly mention when not to use or alternatives, but context is clear.

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

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

Annotations indicate read-only, non-destructive behavior. The description adds significant behavioral context: it groups by asset, fetches price history once, computes model probability using a lognormal model from FRED and live Coinpaprika price, and ranks by |edge|. It also clarifies scope (covers crypto-price bets, V1). 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 concise at four sentences, each serving a distinct purpose: overall function, technical details (V1 specifics), output format, and purpose statement. No redundant or filler content. Front-loaded with the core action.

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

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

Despite lacking an output schema, the description clearly states it returns 'top N ranked by edge magnitude with suggested trade direction.' It explains the internal process adequately for an agent. Annotations cover safety. All three parameters are described in schema. No missing information for a tool of this complexity.

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

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

The input schema has 100% description coverage for all three parameters (limit, window, min_edge_pp), including their types, defaults, and constraints. The description does not add substantial new meaning beyond what the schema provides, though it reinforces the ranking concept. Baseline 3 is appropriate.

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

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

The description explicitly states it scans high-volume Polymarket markets, identifies where Pipeworx data disagrees with market price, and returns top N edges with trade direction. It uses specific verbs ('scan', 'return', 'ranks') and clearly distinguishes from sibling tools like 'polymarket_arbitrage' by focusing on edge detection rather than arbitrage.

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

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

The description directly addresses the target use case: 'Built for the "what should I bet on today" question — agents/users discover opportunities without paging through hundreds of markets by hand.' It implies when to use (opportunity discovery) but does not explicitly state when not to use or mention alternatives beyond the implicit differentiation from siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds context by stating the tool returns prices and spread as an arbitrage signal, and explains the output format. 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 with clear sections for modes and return values. While slightly verbose, every sentence contributes useful information without redundancy.

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

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

Despite lacking an output schema, the description fully explains the return format: per-venue leg prices in 0-1 and spread in percentage points. It also covers mode selection and parameter override behavior, making the tool self-contained.

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 relationship between parameters (topic vs override) and provides concrete examples like 'KXFED-26OCT' and 'fed-decision-in-june-825'.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question, distinguishing it from sibling tools like polymarket_arbitrage by specifying it operates across two different prediction market venues.

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 two usage modes (topic shortcuts vs explicit ticker pairing) with examples, providing clear guidance on when to use each. It does not explicitly contrast with sibling tools but the modes are well-defined.

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

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

No annotations provided, so description bears full burden. It discloses that memories are stored across sessions (persistence) and that omitting key lists all. Could add more on error behavior or memory limits, but the core behavioral traits are clear.

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

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

Two concise sentences. Front-loaded with purpose, then usage. No redundant information.

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

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

Given simple tool (single optional param, no output schema), description is nearly complete. Could mention that memory is session-persistent or that keys are case-sensitive, but not essential.

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

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

Schema coverage is 100% with clear description for 'key'. Description adds value by explaining that omitting key lists all, which is a behavioral nuance not in schema.

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

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

Description clearly states verb 'retrieve' or 'list' and resource 'memory by key'. Distinguishes between retrieving a specific memory and listing all, which differentiates from siblings like 'remember' (store) and 'forget' (delete).

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 omit key to list all, and provides context 'retrieve context you saved earlier'. No alternative tools are mentioned, but the behavior is self-explanatory given sibling names.

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?

With no annotations provided, the description carries full burden. It discloses the parallel fan-out behavior, return structure (structured changes + total_changes count + URIs), and the flexibility of the 'since' parameter. It does not mention error handling or rate limits, but overall it provides good transparency for a tool.

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 at 4 sentences, front-loading the purpose and then detailing behavior, date format, and use cases. Every sentence adds essential information with no filler.

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 (fan-out to multiple sources, flexible date input, no output schema), the description explains the parallel execution, return fields, and acceptable parameter values fairly well. It is missing details about error handling or empty results, but is largely complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining the fan-out logic, the accepted formats for 'since' (ISO and relative with examples), and the fact that 'value' can be a ticker or CIK. It provides context beyond the schema definitions.

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

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

The description clearly defines the tool's purpose: 'What's new about an entity since a given point in time.' It specifies the entity type (company) and the data sources (SEC EDGAR, GDELT, USPTO), distinguishing it from siblings like entity_profile or compare_entities which serve different functions.

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

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

The description provides explicit use cases: 'Use for 'brief me on what happened with X' or change-monitoring workflows.' It explains that the tool fans out to three sources in parallel and supports ISO and relative date formats. However, it does not explicitly mention when not to use it or list direct alternatives.

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

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

The description discloses key behavioral traits beyond any annotations: authenticated users get persistent memory, anonymous sessions last 24 hours. This adds value beyond the structured fields.

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

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

The description is two sentences with no wasted words. The first sentence states the core function, and the second provides usage context. Every sentence earns its place.

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

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

Given the tool's simplicity (2 required params, no output schema), the description is complete enough. It covers purpose, usage context, and persistence behavior. A minor gap is no mention of overwrite behavior for existing keys.

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 provides clear descriptions for both parameters (key and value) with examples, achieving 100% coverage. The description does not add additional meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool stores a key-value pair in session memory, which is a specific verb-resource combination. It also distinguishes the tool from siblings like 'recall' and 'forget' by focusing on storing rather than retrieving or deleting.

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

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

The description provides explicit context for when to use the tool: to save intermediate findings, user preferences, or context across tool calls. However, it does not explicitly say when not to use it or compare to 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?

With no annotations, the description carries the full burden. It explains the tool resolves entities and returns specific outputs, but does not disclose whether it is read-only, any authentication needs, or rate limits. The behavioral context is limited to the single-call efficiency claim, which adds some transparency but not comprehensive safety details.

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 with no redundant words. It is front-loaded with the core purpose and immediately provides concrete details about input and output. Every sentence contributes meaningful 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 tool with two parameters and no output schema, the description covers input variants, output format, and efficiency gains. It does not explicitly state that the tool is safe to call repeatedly (idempotency) or mention error handling, but overall it is sufficiently 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 description coverage is 100%, so the schema already documents both parameters. The description adds value by providing concrete examples (AAPL, 0000320193, Apple) and clarifying that 'value' can be any of those formats, thereby enriching the semantic understanding beyond the schema alone.

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

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

The description clearly states the tool resolves an entity to canonical IDs, specifies the entity type (company), and enumerates input formats (ticker, CIK, name) and output elements (ticker, CIK, company name, URIs). It distinguishes itself by claiming it replaces 2-3 lookup calls, providing clear value and differentiation from potential alternatives.

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

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

The description states the tool replaces multiple lookup calls, implying it should be used over making separate calls for each input type. However, it does not explicitly mention when not to use it or name specific alternative tools, but the context is clear enough for an agent to infer appropriate 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. It aligns with annotations but could mention the API key requirement for certain models to avoid surprises.

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

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

The description is three sentences, each earning its place: first states purpose and method, second gives a use case example, third describes output. No wasted words, front-loaded with the key action.

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

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

Given 4 parameters (all described), comprehensive annotations, and no output schema, the description is complete. It explains the tool's composite nature (uses ai_visibility_check), describes the expected output, and provides a concrete context for use. The missing output schema is adequately compensated by the 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% (each parameter has a description). The tool description reinforces the role of the first entity as the 'subject' and rest as competitors, which is already in the schema. It adds value by describing the output format (ranked list with score, confidence, signal density) that the schema lacks, compensating for the missing output 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 states a specific verb ('Compare AI visibility across multiple entities side-by-side') and identifies the resource ('entities'). It details the process: probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison) by focusing on competitive AI-marketing audits.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and a motivating question ('does Claude know about us as well as our competitors?'), implying when to use. However, it does not explicitly state when to use this tool vs. alternatives like ai_visibility_check (single entity) or compare_entities (general comparison), nor does it mention exclusions or prerequisites.

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?

With no annotations provided, the description carries the full burden. It discloses the return values (verdict, extracted structure, actual value, citation, delta) and the underlying data sources. It doesn't cover side effects or rate limits, but the tool is read-only, so the transparency is adequate.

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 with two well-structured sentences. Every sentence provides critical information: purpose, scope, output, and efficiency benefit. 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?

Given the tool has only one parameter, no output schema, and no annotations, the description is remarkably complete. It explains what the tool does, its domain, what it returns, and its limitations (v1, US public companies). An agent has sufficient context to decide when to call it.

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

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

The schema provides 100% coverage for the single 'claim' parameter with a clear description. The tool description adds value by giving concrete examples ('Apple's FY2024 revenue...'), helping the agent understand expected input format.

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: fact-checking natural-language claims against authoritative sources, specifically company-financial claims. It uses specific verbs ('Fact-check') and resources ('authoritative sources', 'SEC EDGAR + XBRL'), and distinguishes from sibling tools like ask_pipeworx by its specialized domain.

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 defines the supported domain (company-financial claims), mentions it replaces multiple sequential agent calls, and provides a concrete example. However, it does not explicitly state when to avoid using the tool (e.g., non-financial claims) or mention alternatives.

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