Klaviyo

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

Discloses return format (score, confidence, signals, raw_response per model), default model and conditional Anthropic probing, costing implications (BYO key). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

Three sentences, front-loaded with core action, followed by key details and use cases. No redundant phrases.

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

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

Covers return format, costing, and use cases. Lacks explicit mention of error handling or rate limits, but given annotations and schema, it is sufficiently complete for a tool of this complexity.

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

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

Schema coverage is 100%; description adds value beyond schema by explaining the _apiKey passthrough, context disambiguation, and the ability to omit models for default. Clear, meaningful explanations.

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

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

Clearly describes probing LLMs for visibility scoring. Uses specific verbs and resources (probe, score visibility). Distinguishes from siblings like scan_competitor_ai_presence by focusing on generic entity visibility rather than competitor scanning.

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

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

Provides explicit usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not explicitly exclude alternatives or explain when not to use, but the use cases are 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 bears full burden. It discloses that Pipeworx picks the right tool and fills arguments, which is key behavioral info. It does not mention rate limits, authentication needs, or error handling, but for a query tool with simple input, the description is 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 concise (3 sentences) and front-loaded with purpose. Every sentence adds value: first states the function, second explains how it works, third gives examples. 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 (single param, no output schema, no nested objects), the description is nearly complete. It lacks details on response format or error cases, but for a natural language query tool, the description adequately covers what the agent needs to know.

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 one parameter described as 'Your question or request in natural language'. The description adds context that the question should be in plain English and includes examples, which adds meaning beyond the schema. Baseline 3 is appropriate as schema already covers the param 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 accepts natural language questions and returns answers from the best available data source, distinguishing it from sibling tools that are more specific (e.g., Klaviyo tools, discover_tools, recall/remember). The verb 'ask' and resource 'answer' are precise.

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

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

The description explicitly advises to 'just describe what you need' and provides examples, which implies when to use (when you have a natural language request) and not to use (when you need a specific tool action). However, it does not explicitly list alternative tools or when not to use it, so it loses one point.

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, destructiveHint=false, and openWorldHint=true. The description adds substantial behavioral context: it resolves the market, classifies the bet type, fans out to appropriate data packs based on type (e.g., crypto+fred+gdelt for BTC), and returns an evidence packet with 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 a single coherent paragraph with 3-4 sentences. It front-loads the purpose and input, then covers behavior and use cases. It is concise but could be more scannable with bullet points or section breaks.

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

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

Even without an output schema, the description explains the return value: evidence packet and market-vs-model comparison. It covers input, internal logic (bet classification and data fan-out), and provides examples of use cases. For a complex tool, this is very 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%, so baseline is 3. The description reiterates the input formats for 'market' and mentions the enum choices for 'depth' but adds no new meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet + market-vs-model comparison). It distinguishes from sibling tools by claiming it is the core demo product that converts better than alternatives.

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

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

Explicitly provides use cases: 'should I bet on X?', 'what does the data say about this Polymarket market?', 'is there edge in this bet?'. It implies that using this tool is superior to discovering packs individually, but does not name specific alternative tools or state when not to use it.

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

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

No annotations are provided, so the description carries the full burden. It mentions returns 'paired data + resource URIs' but does not explicitly state if the operation is read-only or has side effects. For a query-like tool, this is adequate but could be clearer.

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 plus examples. It front-loads the main purpose and includes no unnecessary 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 no output schema, the description mentions return value type (paired data + URIs) but lacks details on structure or error handling. Adequate for a straightforward comparison tool, but could be more 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% and the description adds meaningful examples (e.g., tickers/CIKs for company, drug names) and constraints (2-5 items). This provides context beyond the schema's own descriptions.

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

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

The description clearly states it compares 2-5 entities side by side, differentiating between company and drug types with specific fields. This is specific and distinguishes from any sibling 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?

The description explains when to use it (to replace 8-15 sequential calls) but does not explicitly state when not to use it or mention alternative tools. However, given the sibling list, no other tool does comparison.

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 cover behavioral traits. It explains that it searches and returns relevant tools with names and descriptions, which is basic. However, it does not mention any side effects, authentication needs, or rate limits. Given no annotations, a score of 3 is appropriate as it conveys core behavior 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?

Three sentences, each earning its place: purpose, what it returns, and when to use. Front-loaded with the key 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 no output schema and low complexity (2 params, no enums, no nested objects), the description is sufficient for an agent to use the tool correctly. It covers purpose, usage, and parameters. Minor gap: does not mention that the tool returns tool names and descriptions (already implied by 'Returns the most relevant tools with names and descriptions'). Score 4.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the query parameter with examples and noting default/max for limit. This elevates the score to 4.

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

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

The description uses specific verbs ('Search', 'Returns', 'Call this FIRST') and clearly identifies the resource ('Pipeworx tool catalog'). It distinguishes from sibling tools by stating it is for searching when you have 500+ tools available, which implies other tools are for specific 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?

Explicitly states 'Call this FIRST' and provides context (when you have 500+ tools available and need to find the right ones). This clearly guides when to use this tool before others.

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 full burden. It declares the tool returns pipeworx:// citation URIs and that it consolidates many calls. It does not discuss error handling or rate limits, but the read-only nature is inferred and performance hint is useful.

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, no redundancy. Front-loaded with core purpose, then details, then alternative 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 moderate complexity and no output schema, the description covers the main behavior (returns URIs for SEC, XBRL, patents, news, LEI). It could be slightly more explicit about the output structure (e.g., JSON object with sections), but it is substantively 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 context: type is currently only 'company', value must be ticker or CIK, and names require resolve_entity. This enhances understanding beyond the schema.

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

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

The description clearly states it returns a 'full profile of an entity across every relevant Pipeworx pack in one call' and enumerates specific data sources (SEC, XBRL, USPTO, GDELT, LEI). It distinguishes itself from sequential calls and the sibling tool usa_recipient_profile.

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

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

Explicitly states when to use (comprehensive profile) and when not (federal contracts go to usa_recipient_profile). Also implies that if only a name is available, use resolve_entity first, guiding the agent to appropriate 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 provided, so description bears full burden. It does not disclose whether deletion is permanent, requires confirmation, or affects other data. The verb 'delete' implies destructive action, but no further context.

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

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

Very concise, single sentence, front-loaded with action and resource. Could be improved by mentioning permanence or side effects.

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 delete tool with one param and no output schema, the description is minimal. It lacks completeness about what happens after deletion (e.g., success indicator, idempotency).

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

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

Schema has 100% coverage with a single parameter 'key' described as 'Memory key to delete'. The description adds no further 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 action (delete) and the resource (stored memory by key). It distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve), though not explicitly.

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

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

No guidance on when to use this tool versus alternatives like 'recall' or 'remember'. The description implies deletion but does not mention prerequisites or 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?

Annotations already indicate readOnly, openWorld, idempotent, non-destructive behavior. The description adds operational steps (fetches page, extracts title/description/key links, outputs markdown) and clarifies the output format, providing useful behavioral insights beyond the annotations.

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

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

The description is a single, well-structured sentence that efficiently conveys purpose, process, and use cases. It is concise without being terse, though a slight split into bullet points could improve scanability.

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 the output is a single text blob ready for deployment. It covers purpose, usage scenarios, and the overall workflow, making it complete for an agent to decide on invocation.

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

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

Input schema covers both parameters with full descriptions (100% coverage). The description does not add additional semantic meaning beyond the schema; it reiterates the default/max for max_links but no new context.

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

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

The description explicitly states the tool generates an llms.txt file for any URL, detailing the extraction process and output format. It clearly differentiates from sibling tools like ai_visibility_check or scan_competitor_ai_presence by focusing on a specific standardized file generation.

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

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

The description provides concrete use cases (indexing a client's site, drafting for own project, auditing competitor) and mentions the output's purpose. While it lacks explicit when-not-to-use or alternatives, the positive guidance is strong and contextualizes the tool well.

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 states 'Returns full campaign details' but does not disclose behavior like rate limits, authentication details beyond the _apiKey parameter, or what happens if the ID is invalid. The description is 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?

Two sentences, front-loaded with purpose. Efficient but could combine into one sentence without loss.

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

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

For a simple retrieval tool with full schema coverage and no output schema, the description is adequate. It lacks any mention of return structure, but for a get-by-ID operation, the description covers the essential purpose.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds no further 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 a single Klaviyo campaign by ID, with a verb (Get) and resource (campaign). However, it doesn't explicitly distinguish it from siblings like klaviyo_list_campaigns, which lists campaigns.

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

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

No guidance on when to use this tool versus alternatives like klaviyo_list_campaigns or other campaign tools. The description does not mention context such as prerequisites (e.g., needing a campaign ID) 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?

Description states 'Returns full profile details', which adds context beyond the empty annotations. However, annotations provide no hints (no readOnlyHint, destructiveHint), so description bears burden. Lacks details on response shape or pagination, but since no output schema exists, description partially compensates. 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?

Two short sentences, front-loaded with action and resource. No fluff. Could arguably merge into one sentence, but clear and 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?

Simple tool with 2 params, no nested objects, no output schema. Description adequately covers purpose and return type ('full profile details'). However, no mention of error conditions or what 'full details' entails. Acceptable for 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% (both parameters described in schema). Description does not add any parameter-level detail beyond schema. Baseline 3 is appropriate.

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

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

Description clearly states verb 'Get', resource 'single Klaviyo profile', and identifier 'by its ID'. Distinguishes from sibling tools like klaviyo_list_profiles (list vs. single). However, does not explicitly contrast with other get tools (klaviyo_get_campaign) but sufficient given resource type differs.

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

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

No explicit guidance on when to use vs alternatives (e.g., klaviyo_list_profiles for listing). No mention of prerequisites like API key requirements (though _apiKey param exists) or that profile_id is needed. Description implies usage for fetching full details but lacks exclusions 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 provided, so the description must carry the behavioral burden. It indicates that the tool can filter by status, but does not disclose pagination, rate limits, or other side effects. A read/list operation is implied, but not explicitly 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?

The description is a single, concise sentence that states the purpose and key capability. No wasted words, but could be slightly more structured (e.g., separating purpose and optional filtering).

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, 100% schema coverage, and no output schema, the description adequately covers the tool's main functionality. However, it lacks details on return format or expected output, which could affect an agent's invocation decision.

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

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

Schema coverage is 100% and the description adds 'draft, scheduled, sent' as example statuses, adding context beyond the schema's filter example. However, it does not explain the filter syntax beyond a brief example.

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

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

The description clearly states it lists campaigns from Klaviyo, with optional status filtering. It differentiates from siblings like klaviyo_get_campaign (single campaign) and klaviyo_list_lists, though not explicitly.

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

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

The description mentions optional filtering by status, providing a usage hint. However, it does not specify when to use this tool versus other listing tools 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?

Annotations are empty, so description carries full burden. It states the tool lists all email lists, but does not disclose any behavioral traits like rate limits, authentication requirements (beyond the API key), or whether results are paginated. Minimal but not misleading.

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, no wasted words. Front-loaded with the core purpose. Could potentially add more context, but it is 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 low complexity (1 param, no output schema), the description is minimally adequate. It lacks details on output format or pagination, but for a simple list operation it is sufficient.

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

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

Schema coverage is 100% with a single parameter (_apiKey) whose description is clear. The tool description does not add any extra 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 lists all email lists in Klaviyo, using a specific verb and resource. It distinguishes from siblings like klaviyo_get_campaign or klaviyo_list_profiles by focusing on lists.

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

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

No explicit guidance on when to use this tool vs alternatives, but the description implies it is for retrieving all lists, which is clear enough. No exclusions or alternatives 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?

No annotations are present, so the description carries the full burden. It discloses that the tool supports optional filtering and page size, which are key behaviors. It does not mention pagination behavior (e.g., if results are limited or how to handle multiple pages), rate limits, or data freshness, but the schema already describes the filter and page_size parameters sufficiently.

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 (two sentences) and front-loads the main action. It avoids unnecessary details, making it efficient.

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

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

Given the tool has no output schema, the description does not explain what is returned (e.g., list of profiles, metadata). It also does not mention pagination limits beyond page_size (max 100). For a list tool with no output schema, some return structure context would be helpful. However, the schema parameters are fully documented.

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 the phrase 'optional filtering and page size', confirming the optional nature of those parameters, but does not add new semantics beyond what the schema already provides. The schema already describes the filter syntax and page size range.

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 profiles (contacts) from Klaviyo, specifying the data source and optional features (filtering and page size). It does not explicitly distinguish it from siblings like klaviyo_get_profile (which gets a single profile) but the intent is 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 mentions optional filtering and page size, implying these can be used to refine results. However, it does not provide guidance on when to use this tool versus other sibling tools (e.g., klaviyo_get_profile for a single profile, or klaviyo_list_campaigns for campaigns).

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 adequately discloses the rate limit and content guidelines (no end-user prompts). However, it does not mention whether a response is expected, if the feedback is anonymous, or any confirmation of receipt. While acceptable for a simple feedback tool, the absence of annotations makes this less complete than ideal.

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

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

The description is extremely concise: three sentences, no filler. It front-loads the purpose in the first sentence, then adds guidelines and constraints. Every sentence earns its place, making it easy for an agent to parse quickly.

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 form tool with no output schema, the description covers the essential information: purpose, usage, constraints, and content guidelines. It could be improved by noting whether there is a confirmation response or any error behavior, but overall it is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% (all three parameters have descriptions). The description adds value beyond the schema by providing guidance on how to write the message (be specific, reference tools/data, avoid prompts) and mentioning the rate limit (which relates to identifier but not a parameter). This extra context improves the agent's ability to use 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 the tool's purpose: 'Send feedback to the Pipeworx team.' It lists specific use cases (bug reports, feature requests, missing data, praise) and distinguishes itself from sibling tools (e.g., data query tools like ask_pipeworx, memory tools like recall), leaving no ambiguity about when to use this tool.

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

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

It explicitly tells when to use (for feedback types), what to include ('Describe what you tried in terms of Pipeworx tools/data'), what to exclude ('do not include the end-user's prompt verbatim'), and a critical constraint (rate limit: '5 messages per identifier per day'). No sibling tool serves a similar purpose, so alternatives are not needed.

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

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

Annotations already declare safety profile (readOnly, idempotent), but description adds valuable details: caching behavior (5min-1h), data source (CF analytics-engine), and privacy guarantee (no PII). No contradiction.

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

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

Four sentences, front-loaded with return type, followed by use cases and technical details. Every sentence 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage, behavior, and limitations comprehensively. Output schema absence is compensated by describing return structure in text.

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 enum and description. Description adds context that shorter windows surface hot trends and longer show steady-state, providing insight 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 tool returns top tools, top packs, and total call volume over recent windows. It distinguishes from siblings by focusing on trending data and explicitly contrasts with 'ask' or 'discover' 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?

Lists three specific use cases (discovering hot data sources, confirming canonical choice, seeing alignment). Does not explicitly state when not to use, but use cases effectively guide selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safety. The description adds valuable behavioral context: it 'walks the child markets, extracts dates/thresholds, sorts them, and reports any pair' and specifies the return format. This fully discloses the tool's operation 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 well-structured and front-loaded with the purpose. It is reasonably concise for the amount of information conveyed (logic, example, return format). However, a slight trimming of the example explanation could make it even more succinct without losing clarity.

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

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

Given the moderate complexity and absence of an output schema, the description provides complete information: it explains the tool's logic, required input, and the structure of returned data ('list of {market_a, market_b, gap_pp, suggested_trade}'). No further details are necessary for correct usage.

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

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

With 100% schema description coverage, the input parameter 'event' is already described. The description enhances this by explaining the expected format ('Polymarket event slug or URL') and how it is used to find child markets. This extra context adds significant value 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's purpose: 'Find arbitrage opportunities within a Polymarket event by checking for monotonicity violations.' It explains the specific logic and provides an example, making the action and resource unambiguous. The purpose is unique among sibling tools like polymarket_edges and bet_research, though not explicitly differentiated.

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

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

The description gives clear guidance on when to use the tool (for arbitrage detection in Polymarket events with multiple by-date or by-threshold markets) and what input to provide (event slug or URL). However, it does not explicitly state when not to use it or suggest alternative tools, which would improve this dimension.

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 openWorldHint. The description adds valuable behavioral details: it uses external data (FRED, coinpaprika), computes model probability, groups by asset, and fetches each asset's price history 'ONCE'. This informs the agent about the tool's internal process without contradicting 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 a front-loaded main sentence followed by supporting details. While it is somewhat lengthy, each sentence adds value (e.g., explaining the model, grouping, output format), making it appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description effectively explains what the tool returns ('top N ranked by edge magnitude with suggested trade direction'). Combined with the schema coverage and annotations, it provides sufficient context for an agent to understand the tool's functionality 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?

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description restates these briefly ('Top N edges', 'volume window', 'minimum edge') but does not add new meaning beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states that the tool scans high-volume Polymarket markets and returns those where Pipeworx data disagrees most with market price, with a specific verb ('Scan') and resource ('high-volume Polymarket markets'). It explicitly mentions the use case ('what should I bet on today'), making its purpose unambiguous and distinct from 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 provides a clear context for use ('Built for the 'what should I bet on today' question'), implying when to invoke it. However, it does not explicitly exclude scenarios or mention alternatives among sibling tools, leaving some room for ambiguity.

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, so the description does not need to repeat those. The description adds context about the two modes and return format, which is consistent and useful.

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

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

The description is front-loaded with the core purpose, then explains context and modes. It is somewhat verbose but each sentence adds value. Could be slightly tighter for higher score.

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

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

The description explains the return format (prices and spread) despite no output schema. It covers main use cases but lacks mention of error handling or edge cases, which is acceptable given the tool's 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%, but the description adds significant meaning by explaining the two modes (topic vs explicit) and how parameters interact (overrides). This goes beyond the schema's field 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 states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' which clearly identifies the tool's function. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 the spread arises due to different participant pools and is an arbitrage signal, suggesting when to use the tool. However, it does not explicitly compare with siblings or state when not to use it.

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

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

No annotations provided, so the description carries full burden. It discloses the dual behavior (retrieve by key vs list all) and mentions persistence across sessions, which is good context for a read-only operation.

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 core action, no wasted words. Efficient and complete.

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 no output schema and low complexity, the description is complete enough. It covers retrieval and listing, and mentions cross-session persistence.

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 one optional parameter. The description adds context about listing all keys when omitted, which the schema's description doesn't fully convey.

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 previously stored memory by key or lists all memories if key is omitted. It distinguishes itself from sibling tools like 'remember' (store) and 'forget' (delete) by focusing on retrieval and 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?

The description explains when to use it: to retrieve context saved earlier. It doesn't explicitly mention when not to use it or list alternatives, but the context is clear for a simple memory tool.

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

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

No annotations provided, so description carries full burden. Describes parallel fan-out and return structure (structured changes, count, URIs). Does not discuss rate limits, error behavior, or authentication needs.

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-loads purpose, efficiently packs details on fan-out, date formats, and return values. 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?

Covers parameters, returns, and use cases. Lacks specifics on result limits or what 'structured changes' entail, but given no output schema, is fairly complete for a monitoring 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%, and description adds valuable context: explains 'since' accepts ISO dates and relative formats with examples, 'type' is limited to 'company', and 'value' can be ticker or CIK. This enhances understanding beyond the JSON schema.

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

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

Clearly defines the tool as showing what is new about an entity since a given point in time, specifies the entity type 'company' and the data sources (SEC EDGAR, GDELT, USPTO). Distinguishes from siblings like 'entity_profile' and 'compare_entities'.

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

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

Explicitly states use cases: 'brief me on what happened with X' or change-monitoring workflows. Lacks explicit when-not-to-use or comparisons to alternatives, 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?

With no annotations, the description carries full burden. It discloses persistence behavior ('authenticated users get persistent memory; anonymous sessions last 24 hours'), which is beyond the basic 'store' action. No contradictions with annotations (none provided).

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, concise and front-loaded. No wasted words, but could potentially be even 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 no output schema and simple input schema, the description is complete enough. It explains purpose, usage context, and persistence behavior. No obvious gaps.

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

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

Schema coverage is 100% and includes examples for 'key' and a description for 'value'. The description adds no additional parameter details 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 it stores a key-value pair in session memory, distinguishing it from siblings like 'recall' and 'forget'. The verb 'store' and resource 'key-value pair in session memory' are specific.

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 ('save intermediate findings, user preferences, or context across tool calls') and distinguishes between authenticated and anonymous sessions. However, it does not explicitly say when not to use it or name alternative tools.

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

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

Without annotations, the description adequately discloses behavior: it returns ticker, CIK, company name, and pipeworx:// resource URIs. It mentions the v1 constraint and that it replaces multiple calls. No destructive behavior is indicated, and no contradictions are present.

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, consisting of three sentences that are front-loaded with the main purpose. Every sentence adds value without repetition or unnecessary detail, earning its place in the description.

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

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

Given the tool has only two parameters and no output schema, the description sufficiently covers both input and output. It explains what the tool does, what inputs it accepts, and what outputs it produces, making it complete for an AI agent to understand and invoke correctly.

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

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

The input schema has 100% description coverage for both parameters, but the description adds meaningful context beyond the schema. It explains the v1 support for company type, provides concrete examples (AAPL, 0000320193, Apple), and specifies the return format including pipeworx:// URIs, enhancing the schema's information.

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 in a single call. It uses a specific verb (resolve) and resource (entity to canonical IDs), and distinguishes itself from siblings by noting it replaces 2-3 lookup calls, making it distinct from ask_pipeworx which may be a general query tool.

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

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

The description provides explicit context for when to use the tool, such as resolving companies with ticker, CIK, or name. It implies efficiency gains but does not explicitly state when not to use it or name alternative tools beyond the implied multi-call alternative, leaving some room for ambiguity.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds behavioral context beyond that: it explains that it internally calls ai_visibility_check for each entity, treats the first entity as the subject, and returns a ranked list with score, confidence, and signal density. No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the main action, and each sentence adds specific information. No redundant or unnecessary words. 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 the tool's moderate complexity, no output schema, and multiple siblings, the description fully explains the input, behavior, and output format (ranked list with score, confidence, signal density). It covers all necessary details for an agent to use the tool correctly.

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

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

Input schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that 'entities' should be 2-8 with first as subject, that 'models' defaults to workers-ai, and the purpose of the optional params. This enriches the agent's 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 that the tool compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, ranks them, and surfaces the most/least recognized. It gives a concrete use case and distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a clear context for usage (competitive AI-marketing audits) and implies that for a single entity one would use ai_visibility_check, but it does not explicitly state when not to use this tool or offer direct alternatives. The guidance is useful but lacks exclusion criteria.

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

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

With no annotations provided, the description carries the full burden. It discloses the return components (verdict, structured form, actual value with citation, percent delta) and the data source (SEC EDGAR + XBRL). It also mentions the possible verdicts. It lacks details on failure modes or limits, but is transparent about the tool's behavior.

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

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

Three sentences with no wasted words. The purpose is front-loaded, and each sentence adds essential information: what it does, supported domain, output summary, and value proposition.

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 parameter, no output schema, and no annotations, the description is fairly complete. It covers the domain, input type, output components, and use case. It could mention error handling or unsupported claim types, but overall it provides sufficient context for an AI 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?

The schema already has 100% coverage with a description for the single 'claim' parameter. The description adds examples but does not significantly enhance meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description starts with a specific verb-resource pair: 'Fact-check a natural-language claim against authoritative sources.' It clearly distinguishes the tool from siblings by stating it replaces 4-6 sequential agent calls and specifies the supported domain (company-financial claims via SEC EDGAR + XBRL).

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

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

The description explicitly states the supported claim types (revenue, net income, cash for public US companies) and hints that the tool is a consolidated alternative to sequential agent calls. However, it does not explicitly state when not to use the tool, but the context is clear enough.

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