Amplitude

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 value by explaining the scoring per model, the return structure (score, confidence, signals, raw_response), cost implications (Anthropic requires BYO key and you pay Anthropic directly), and that workers-ai is free. This adds behavioral context beyond annotations, especially about cost and API key usage.

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: two sentences plus a line about return structure and use cases. It is front-loaded with the core function, then provides details on defaults and return format. Every sentence earns its place; no wasted words. Structure is logical and easy to parse.

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

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

Given the tool has no output schema, the description compensates by specifying the return structure: 'per-model {score, confidence, signals, raw_response} + a combined view.' It explains the purpose of all parameters, including the optional _apiKey and context. It covers cost implications and appropriate use cases. The description is complete and leaves no major gaps for an AI agent to understand how to use 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 meaning to parameters: it explains entity as 'brand/business name, product name, person, or topic' with examples, models as 'which models to probe' with supported models mentioned, _apiKey as 'optional Anthropic API key' with the note that it's passed straight through, and context as 'a phrase locating the entity to disambiguate.' This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's action: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies the resource (LLMs), the action (probe and score), and the scope (specific entity). It distinguishes from siblings by mentioning unique use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring' that are not covered by other tools such as entity_profile or scan_competitor_ai_presence.

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

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

The description provides clear usage context: default model is workers-ai, and to use Anthropic you need to pass _apiKey. It explains when to use it ('useful for AI-marketing audits, pre-launch brand checks, competitive monitoring'). However, it does not explicitly state when not to use this tool or discuss alternative tools that might be more appropriate, such as the sibling 'scan_competitor_ai_presence' which might overlap.

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 must carry behavioral burden. It discloses it returns counts for a date range, but does not mention whether authentication is required (implied by required API keys), rate limits, or data freshness. The description is adequate but lacks depth for a data access 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 one sentence, efficient and front-loaded. It conveys core purpose without extra words. Could be slightly more informative about the 'm' parameter, but overall 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 5 parameters (4 required) and no output schema, the description is complete for a simple data retrieval tool. It covers the main function but omits details like return format or error cases. For a tool with required API keys, mentioning authentication in description would be helpful.

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 does not add parameter details beyond schema (e.g., date format YYYYMMDD is in schema). It implies the metric parameter exists but does not clarify 'm' values beyond what schema provides. No extra meaning added.

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 active user counts (daily/weekly/monthly) for a date range. It specifies the verb 'get' and resource 'active user counts', but does not explicitly distinguish from siblings like amp_get_events or amp_get_retention, though the metric focus (active users) differentiates it implicitly.

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 (for active user counts) but provides no guidance on when not to use or alternatives. Siblings exist (e.g., amp_get_retention) but no exclusions are given. The date range scope is clear, but no context on prerequisite data or limitations.

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 mentions it returns event counts and breakdowns, which adds some context. However, there are no annotations provided, so the description carries full burden. It does not disclose authentication requirements (though _apiKey and _secretKey are in schema), rate limits, data freshness, or potential errors.

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 one sentence, front-loading the main purpose. It could be slightly improved by adding a second sentence for when to use, but current structure is 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 no output schema, the description partially explains return values. With 6 parameters, the description is minimal but acceptable. However, it lacks context about the tool's scope (e.g., what segmentation means, how grouping works) which might be necessary for correct use.

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

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

Schema description coverage is 100%, so the schema already describes each parameter. The description adds 'event counts and breakdowns' which implies the output, but does not elaborate on how parameters affect results. Baseline 3 is appropriate as schema does the heavy lifting.

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 event segmentation data from Amplitude for a date range, specifying it returns event counts and breakdowns. However, it does not explicitly distinguish it from siblings like amp_get_active_users or amp_get_retention.

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 is provided on when to use this tool vs alternatives. It does not mention when to use amp_get_events over amp_get_active_users or amp_get_retention, nor does it specify any 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?

With no annotations, description partially covers behavior: it returns time-series data. But lacks details like whether data is aggregated, time granularity, or any side effects. Acceptable for a read-only 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?

Two concise sentences, front-loaded with purpose. No unnecessary words. Could benefit from specifying the retention type from schema.

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

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

Given no output schema and moderate complexity (5 params), the description is adequate but minimal. Missing details like return format, date format validation, or example values.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about the overall purpose (retention data) but doesn't detail individual parameters beyond schema. However, it correctly implies date range usage.

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

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

The description clearly states it retrieves retention data for a date range and explains the purpose (showing user return over time). It distinguishes from siblings like amp_get_active_users which focus on active users, but could be more specific about the metric.

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 vs alternatives like amp_get_active_users or amp_get_events. Does not specify prerequisites (e.g., need API keys) or typical 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?

No annotations are provided, so the description carries the burden. It discloses that the tool returns 'recent event activity' but does not describe behavioral traits such as auth requirements (though _apiKey and _secretKey are parameters), rate limits, or what 'recent' means. It adds minimal context beyond the schema.

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

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

The description is a single, concise sentence that front-loads the purpose. Every word is necessary, and there is 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 has 5 parameters (100% schema coverage) and no output schema, the description is somewhat complete but lacks behavioral context. It explains what it does but not the response format or any edge cases. With no annotations, more detail would be beneficial.

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 baseline is 3. The description does not add meaning beyond the schema; it merely mentions 'Amplitude ID' which is already described in the schema. No additional parameter guidance is provided.

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 the verb 'Get' and resource 'recent event activity for a specific user', clearly indicating what the tool does. It differentiates from siblings like amp_get_events (which may not be user-specific) and amp_get_active_users (which focuses on active users). However, it does not explicitly distinguish from all siblings.

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 context by specifying 'for a specific user by their Amplitude ID', but it does not provide explicit guidance on when to use this tool vs alternatives like amp_get_events or amp_user_search. It lacks when-not-to-use or alternative recommendations.

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 carry the burden. It states the tool returns matching user profiles, but does not disclose any limitations, permissions required, or side effects. Since the tool likely requires API and secret keys (implied by parameters), the description does not add much beyond that.

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, clearly stating the purpose. No wasted words.

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

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

Given the tool has 3 parameters all described in schema, and no output schema, the description is sufficient to understand the tool's function. It could mention the return format (e.g., list of profiles) but the description implies this. Completeness is high.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds that the 'user' parameter is a search term for email, user_id, or Amplitude ID, which adds value. However, the API and secret key parameters are not elaborated on in the description.

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

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

The description clearly states the tool searches for a user by user property or user ID and returns matching user profiles. The verb 'search' and resource 'user' are specific, and the scope (returning profiles) distinguishes it from sibling tools like amp_get_user_activity.

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 this tool is for finding users, but it does not explicitly state when to use this over other tools like amp_get_user_activity. However, given the sibling tools cover different functionality (active users, events, retention), usage is fairly 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?

Since no annotations are provided, the description carries full burden. It discloses that the tool internally selects tools and fills arguments, returning a result. This adds transparency about its orchestration behavior. However, it does not mention any limitations, potential delays, or failure modes.

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

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

The description is very concise, with three sentences covering purpose, behavior, and examples. No filler. 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 the tool's simplicity (single parameter, no output schema) and the orchestration nature, the description is quite complete. It explains what the tool does and how to use it. A slight gap is not discussing potential ambiguity or clarification mechanisms.

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 for the single parameter 'question' with a description. The description adds value by explaining how to use the parameter ('describe what you need' and examples), but the schema already covers the meaning. 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 uses a clear verb ('Ask a question') and specifies the resource ('get an answer from the best available data source'). It explicitly states that Pipeworx selects the right tool and fills arguments, distinguishing it from sibling tools that are direct tools. The examples provide concrete 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?

The description advises 'just describe what you need' and provides examples, implying when to use this tool (when the user wants a natural language answer) vs. browsing tools directly. However, it does not explicitly state when not to use it or mention alternatives (the sibling tools themselves).

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, destructiveHint=false. Description adds behavioral details: it resolves the market, classifies the bet type, fans out to appropriate data packs (e.g., crypto+fred+gdelt), and returns an evidence packet plus comparison. 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 about 6 sentences, which is reasonable for the tool's complexity. It front-loads the core action (research a Polymarket bet) and progressively details inputs, internal logic, and outputs. Slightly long 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?

No output schema, but the description explains return value (evidence packet plus market-vs-model comparison). It covers three input formats and internal fan-out logic. Missing details on error handling or non-existent markets, but overall sufficient for agent understanding.

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

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

Schema description coverage is 100%, but the description adds significant value: for 'market' it explains it can be a slug, URL, or question text (schema only says slug or URL). For 'depth', it provides concrete numbers ('quick = 2-3 evidence sources, thorough = full fan-out'). This goes beyond the schema's enum and default.

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 researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). This distinguishes it from sibling tools like validate_claim or resolve_entity, which are more generic.

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

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

The description explicitly lists use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It also frames the tool as the core demo product. It doesn't explicitly state when not to use, but the context is clear.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions data sources (SEC EDGAR, FDA) and output format (paired data, resource URIs), but lacks information on permissions, rate limits, or error behavior (e.g., missing entities).

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 sentences, front-loaded with purpose, no redundancy. Every sentence adds essential information (purpose, types, data, efficiency benefit).

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

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

For a tool with 2 parameters and no output schema, the description covers the main use cases and output format. It lacks details on error handling or edge cases, but overall it is fairly complete for the given complexity.

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

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

Schema coverage is 100% (both parameters described). The description adds value by explaining what data is returned for each entity type and the resource URI output, exceeding the schema's basic 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 explicitly states 'Compare 2–5 entities side by side in one call' and specifies two entity types (company, drug) with distinct data fields. It distinguishes from sequential agent calls, making the purpose very clear.

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

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

The description notes it 'replaces 8–15 sequential agent calls', implying efficiency context. However, it does not explicitly state when not to use this tool or compare it to siblings like resolve_entity, but the context is clear enough for basic use.

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

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

The description discloses the tool's behavioral trait of returning 'most relevant tools with names and descriptions,' which is important for agent decision-making. Since no annotations are provided, the description carries the full burden, and it does so adequately by explaining the search-and-return behavior. It could mention if results are ordered by relevance or any caveats, but it's sufficiently transparent.

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

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

The description is two sentences long, front-loaded with the core action, and every sentence provides value: the first explains what the tool does, the second gives explicit usage guidance. No wasted words.

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

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

Given the tool's simplicity (2 parameters, no output schema, no annotations), the description is nearly complete. It explains the purpose, when to use it, and what it returns. The only minor gap is not explicitly stating that it searches by semantic matching (though implied by 'natural language description'). It doesn't need to explain return values since there's no output schema, but a brief note on the result format would be ideal.

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 descriptions for both parameters ('query' and 'limit'), achieving 100% schema coverage. The description adds context by mentioning the default and max for 'limit' (20 and 50), which is helpful. However, it doesn't add new semantic meaning beyond what the schema offers, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: searching the Pipeworx tool catalog by describing what you need. It specifies the verb ('Search'), the resource ('Pipeworx tool catalog'), and the outcome ('Returns the most relevant tools'). This effectively distinguishes it from sibling tools, which are action-specific (e.g., amp_get_active_users) or memory-related (remember/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 this tool: 'Call this FIRST when you have 500+ tools available and need to find the right ones.' It provides clear guidance on the context (large tool catalog) and the task (finding relevant tools), leaving no ambiguity about its role compared 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?

With no annotations, the description takes full burden. It details what data is returned and that it bundles multiple data sources. It implies read-only behavior but does not explicitly state it, nor mention rate limits or authentication. Still, it is largely transparent.

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 with no redundant sentences. It front-loads the core purpose, lists data sources, mentions return format, and provides exclusion guidance. Every sentence adds value.

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

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

Given the tool has only 2 parameters, no output schema, and no annotations, the description compensates well by explaining the data returned and limitations (only company). It lacks an explicit output structure, but the URI format is mentioned. Slight gap in output formatting details.

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 parameter descriptions already explain type (only company) and value format (ticker/CIK). The main description adds context about data returned for company type, but does not deeply enrich parameter semantics beyond the schema.

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

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

The description clearly states the tool retrieves a full profile of an entity across multiple Pipeworx packs, lists specific data sources (SEC filings, XBRL financials, patents, news, LEI), and mentions returning citation URIs. It distinguishes from siblings like resolve_entity 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?

The description explicitly says when to use this tool (for comprehensive company profiles) and when not to (federal contracts: use usa_recipient_profile). It also hints that names require resolve_entity first, providing clear guidance.

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

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

No annotations are provided, so the description must carry the full burden. It states deletion is permanent ('delete'), but does not clarify if the operation is irreversible, what happens to related data, or any side effects. This is acceptable for a simple delete tool 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, concise sentence that directly states the action and object. No unnecessary words; every part adds value.

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

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

Given the tool's simplicity (single required parameter, no output schema, no nested objects), the description is adequate. However, it could mention that deletion is permanent or that the key must exactly match a stored memory.

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 the 'key' parameter. The description adds no additional meaning beyond the schema, meeting the baseline 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 uses a strong verb-resource pair ('Delete a stored memory by key') that clearly distinguishes this from siblings like 'remember' (store) and 'recall' (retrieve). It explicitly states the action and the identifier.

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 that 'forget' is for deletion, but does not specify when to use it vs. alternatives (e.g., 'recall' for reading, 'remember' for writing). No explicit exclusions or context are given.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavior details: 'Fetches the page, extracts title/description/key links, emits standard markdown format'. This complements the 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 concise and front-loaded, stating the core purpose first followed by use cases. It avoids unnecessary words but could be slightly more compact.

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 params, no output schema), the description covers purpose, behavior, output format, and use cases. It does not mention error handling or limitations, which is acceptable for a straightforward 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?

Both parameters (url, max_links) are fully described in the schema (100% coverage). The description does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Generate a production-ready llms.txt file for any URL'. It specifies the action (generate), resource (llms.txt), and context (for AI crawlers). The tool is distinct from siblings which focus on other domains.

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 (indexing client sites, drafting for own project, auditing competitors) which provide clear context. However, it does not explicitly mention when not to use or provide alternatives, though no similar siblings exist.

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 carries the full burden. It discloses rate-limiting (5 per day) and content constraints (describe Pipeworx context, no end-user verbatim). The behavior is clearly described with 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 three sentences, front-loaded with purpose, and every sentence provides essential information without redundancy. It is concise and well-structured.

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

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

For a simple tool with 3 parameters and no output schema or annotations, the description covers all necessary aspects: purpose, usage guidelines, rate-limiting, and content constraints. It is complete for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds value beyond the schema by explaining the tool's purpose, the optionality of context, and the rate limit. The schema already has detailed enum descriptions, so the description complements it 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?

The description clearly states the tool's purpose: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, missing data, praise) and distinguishes from sibling tools (none of which are for feedback).

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

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

The description explicitly states when to use the tool (bug reports, feature requests, etc.) and provides constraints (do not include end-user prompt, rate-limited to 5 per day). It does not explicitly mention alternatives, but the unique purpose among siblings makes it clear.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that results are self-aggregating, from CF analytics, no PII, and cached 5min-1h. 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 the main output first, then use cases, then details. It is slightly lengthy but 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 parameter and no output schema, the description covers purpose, usage, data source, caching, and privacy. It could detail output format, but the description of returned items 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?

Schema coverage is 100% and the parameter description is clear. The description adds value by explaining the trade-offs between short and long windows, enhancing the enum choices.

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

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

The description clearly states that the tool returns top tools, packs, and call volume over a window, and distinguishes itself from siblings like 'discover_tools' by focusing on real-time usage by AI agents.

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 concrete use cases are provided: discovering hot data sources, confirming canonical tools, and aligning use case with trends. However, no explicit when-not-to-use or alternatives are given.

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

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

The description details the internal process: walks child markets, extracts dates/thresholds, sorts, and reports violations. It aligns with annotations (readOnlyHint=true) and adds value beyond them by explaining the monotonicity rule and output format.

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

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

The description is a single well-organized paragraph: purpose, concept explanation, usage, behavior, and output format. Every sentence is informative and necessary, with no redundancy.

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

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

Given the tool has one required parameter and no output schema, the description fully explains the input, logic, and output (list with fields). It provides sufficient context for an agent to invoke it 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 single parameter 'event' is fully described in the schema (100% coverage), and the description adds an example and clarifies it can be a slug or URL, enhancing understanding.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and explains the specific rule. It distinguishes itself from siblings like 'polymarket_edges' and 'bet_research' by focusing on within-event monotonicity checks.

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

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

It explicitly says to pass a Polymarket event slug or URL, providing usage context. However, it does not mention when not to use the tool or alternative tools for this purpose, which would strengthen the guidance.

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

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

Annotations indicate readOnly and openWorld. The description adds value by detailing the internal algorithm: uses lognormal model from FRED and live coinpaprika price, groups by asset, fetches price history once, and ranks by edge. It also notes V1 scope covers crypto-price bets. 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 purpose, method, output, and use case. It is slightly verbose but each sentence adds meaningful detail. Could be condensed slightly 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 three parameters and no output schema, the description covers algorithm, inputs, and output intent (ranked edges with suggested direction). However, it lacks explicit format of returned edges (e.g., fields), which would aid agent interpretation. Generally complete for deciding when to invoke.

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

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

All three parameters have schema descriptions (100% coverage). The description adds default values (limit=10 max=25, window=1wk, min_edge_pp=0.5) and explains the role of limit in ranking. This context enhances usability 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 scans highest-volume Polymarket markets and returns those with largest disagreement between Pipeworx model and market price. It specifies the verb 'scan' and resource 'Polymarket markets', and distinguishes from sibling tools like polymarket_arbitrage by focusing on model-derived edges.

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 targets the 'what should I bet on today' use case and mentions it saves paging through hundreds of markets. It implies usage for initial opportunity discovery but does not explicitly state when not to use or mention alternatives like bet_research for deeper analysis.

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 confirm read-only, idempotent, non-destructive behavior. The description adds significant context: it explains the price difference rationale, details the return format (leg-by-leg prices and spread in percentage points), and describes the two operation modes, all beyond what annotations provide.

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

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

The description is compact and well-structured: first sentence states overall purpose, then background/motivation, then clearly enumerated modes, and finally return format. Every sentence adds value, no 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?

Given no output schema, the description compensates by detailing return format. It covers the main use cases and modes. However, it does not mention error handling (e.g., if a topic or explicit ticker is invalid), nor does it explicitly contrast with sibling tools. Still, for a read-only data tool, it is reasonably 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 descriptions are already rich (100% coverage with examples). The tool description adds the crucial semantic relationship between parameters: topic is pre-mapped, explicit overrides are possible, and the two modes are mutually exclusive yet combinable. This adds meaning beyond individual 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 calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question, with specific verb+resource and two usage modes. It distinguishes from sibling tools like polymarket_arbitrage by emphasizing the cross-venue aspect.

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 modes (topic shortcuts and explicit pairing) and provides context on when the spread is a real arb signal. However, it lacks explicit guidance on when to avoid this tool in favor of siblings like polymarket_arbitrage, which might be used for single-venue analysis.

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 description carries the burden. It discloses that omitting the key lists all memories, but does not mention behavior if key is missing or if memory doesn't exist, nor any side effects. Given no annotations, a 3 is reasonable.

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, clear and front-loaded. Each sentence adds value. Slightly verbose phrasing ('previously stored', 'saved earlier') could be tightened.

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

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

Given the tool is simple (1 optional param, no output schema), the description covers the essential use case. Could mention return format (e.g., returns memory content) but not necessary given simplicity.

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 meaning beyond schema by explaining that omitting the key lists all memories, but does not provide additional detail about the key parameter (e.g., format, case-sensitivity).

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

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

The description clearly states the action ('Retrieve') and resource ('stored memory'), and distinguishes between retrieving by key vs listing all. This differentiates it from sibling tools like 'remember' and 'forget'.

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

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

The description tells when to use it ('to retrieve context you saved earlier'), and implies when not to (if you want to store, use 'remember'). However, it does not explicitly mention 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?

With no annotations provided, the description carries full burden. It describes parallel fan-out behavior, input format details, and return structure (structured changes, count, URIs). It does not explicitly state non-destructiveness or rate limits, but the described read-only nature is 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?

The description is extremely concise—two sentences that front-load the purpose and then provide essential behavioral details. Every sentence adds value with no redundancy or 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?

Despite no output schema, the description mentions return components (structured changes, total_changes count, pipeworx:// URIs) and explains data sources and parallelism. It provides all necessary context for an agent to understand the tool's operation and output.

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

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

Schema covers all parameters (100% coverage), so baseline is 3. The description adds value by explaining the behavior of 'since' (ISO date or relative), 'value' (ticker or CIK), and the overall tool flow (parallel lookups), going beyond 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 states the tool's function (shows what's new about an entity since a given time) and specifies supported entity type (company) with data sources (SEC, GDELT, USPTO). It distinguishes itself from sibling tools like entity_profile and compare_entities by focusing on temporal changes.

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 for "brief me on what happened with X" or change-monitoring workflows,' providing clear usage context. It does not mention when not to use or alternative tools, but the guidance is sufficient for typical scenarios.

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

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

No annotations are provided, so the description carries the full burden. It discloses persistence behavior (authenticated vs. anonymous), which is useful. However, it does not mention overwrite behavior, memory limits, or data retrieval methods. Given the absence of annotations, a score of 3 is reasonable.

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

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

The description is concise with three sentences, front-loading the core purpose. The last sentence adds useful but non-essential detail about persistence. It could be slightly more efficient by removing redundancy, but overall it is well-structured.

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

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

For a simple key-value store tool with 2 parameters and no output schema, the description covers the essential use cases, persistence model, and example keys. It lacks details on overwriting and limits, but given the tool's simplicity, it is largely 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%, but the description adds meaning beyond the schema by clarifying that values can store 'findings, addresses, preferences, notes'. It also provides example keys in the schema. The description effectively complements 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 stores a key-value pair in session memory, specifying the verb 'store' and resource 'key-value pair'. It distinguishes from sibling tools like 'forget' (which likely removes) and 'recall' (which retrieves).

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 use: saving intermediate findings, user preferences, or context across tool calls. It also mentions persistence differences between authenticated users and anonymous sessions. However, it does not explicitly state when not to use this tool or mention 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?

No annotations are provided, so the description carries full burden. It discloses return fields (ticker, CIK, name, URIs) and versioning (v1 only company), but lacks details on error handling, authentication, or side effects. 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 two sentences, front-loads the core purpose, and every sentence earns its place. No fluff or 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 the tool's simplicity (2 params, no output schema, no annotations), the description covers the essential functionality. It could mention failure modes or multiple match handling, but for v1 it is reasonably 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?

Input schema has 100% description coverage, but the description adds value by providing concrete examples (e.g., 'AAPL', '0000320193', 'Apple') and clarifying the 'type' enum scope. This helps understanding beyond the schema.

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

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

The description clearly states the tool resolves an entity to canonical IDs across Pipeworx data sources, specifies current support for type 'company', and distinguishes itself by replacing 2-3 lookup calls. The verb 'resolve' and resource 'entity' are specific and unambiguous.

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

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

The description implies when to use (to get canonical IDs efficiently) and mentions it replaces multiple calls, but does not explicitly state when not to use or provide direct alternatives among siblings. Sibling tools like 'amp_get_*' are related but not compared.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds details about internal probes, ranking by score, and returning confidence and signal density per entity, which goes beyond the annotations.

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

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

Four sentences clearly conveying purpose, mechanism, use case, and output. No redundant or tangential information. 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?

Given no output schema, the description explains what is returned (ranked list with score, confidence, signal density). It mentions internal tool usage and parameter roles. Could mention limits on entity count (2-8) but that's in schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity in the array is treated as the 'subject' for narrative, and the rest as competitors. It also clarifies that context disambiguates common names.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, and ranks results. It distinguishes itself from the sibling tool ai_visibility_check by focusing on multiple entities side-by-side.

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 it's useful for competitive AI-marketing audits and gives an example query. It implies a single entity check should use ai_visibility_check, but does not state exclusions or alternative tools.

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

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

No annotations are provided, so the description carries the full burden. It mentions the version, supported claim type, and output format but does not disclose potential errors, rate limits, or behavior for unsupported claims. This is adequate but could be more transparent.

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 concise sentences, front-loading the purpose, then limitations, then output details. Every sentence adds value with no repetition 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 single parameter, no output schema, and no annotations, the description covers the essential aspects: input type, supported claims, output format, and benefits. Missing details about error handling but still fairly complete.

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

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

The schema covers the single parameter 'claim' with 100% description coverage. The description adds significant value by specifying the scope (company-financial claims for US public companies) and the output structure, which is not present in the schema.

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

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

The description clearly states it fact-checks natural-language claims against authoritative sources, specifically company-financial claims for US public companies, returning verdicts and details. This distinguishes it from sibling tools which focus on analytics and memory operations.

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 that it replaces 4-6 sequential agent calls, indicating when to use it. It also notes that v1 supports only company-financial claims, setting clear boundaries. However, it does not explicitly mention alternatives 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.