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

Annotations declare readOnlyHint=true, so the tool is a safe read operation. The description adds that it returns ranked results based on various metrics, which is consistent with read-only behavior. It does not disclose any unexpected side effects or limitations, but the annotation already covers the main behavioral trait.

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

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

The description is extremely concise with only three sentences. It front-loads the primary purpose, then adds requirements and a usage hint. Every sentence adds value without redundancy or filler.

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

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

Given 8 parameters, 100% schema coverage, and a read-only annotation, the description provides key context: purpose, required params, prerequisite, and example use cases. An output schema is absent, but the output is implied (list of top performers). The description is sufficient for an AI agent to understand the tool's role without 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%, with detailed descriptions for each parameter (e.g., level has enum values explained). The description mentions the required parameters and their roles but does not add significant meaning beyond the schema. It provides context for adAccountId (where to get it), but that is already in the schema description. 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 retrieves top performing ads/campaigns ranked by metrics like revenue and ROAS for a date range. It uses a specific verb ('Get'), identifies the resource ('top performing ads/campaigns'), and distinguishes from other hyros tools by focusing on ranking and performance metrics.

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

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

The description provides explicit use cases ('what are my best ads this week?', 'which campaigns have the highest ROAS this month?') and a prerequisite ('Use hyros_get_sources to find your ad account IDs first'). It does not explicitly state when not to use the tool or compare to alternatives, but the context is clear enough for correct 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 declare readOnlyHint=true, and the description confirms a read-only comparison operation. It adds contextual value by listing specific returned metrics (revenue, cost, ROAS, etc.) and percentage changes, which are not in the schema. There are no contradictions. The description does not disclose potential behavioral details like data freshness or pagination, but given the read-only nature, this is adequate.

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

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

The description is two sentences: the first clearly states the tool's purpose and requirements; the second lists output metrics and a concrete use case. There is no redundant information, and every sentence earns its place. It is appropriately front-loaded 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's complexity (8 parameters, 6 required, no output schema), the description covers the core functionality, input requirements, and output. It lacks details about potential constraints (e.g., non-overlapping periods) or how to interpret percentage changes, but the use case example compensates partially. The presence of annotations and full schema coverage reduces the burden on the description.

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

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

Schema description coverage is 100%, so baseline is 3. The description mentions 'Requires an ad account ID and level' and hints at date usage via the example, but does not add new meaning beyond what the schema already provides for each parameter. No additional constraints or format guidance are given.

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

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

The description uses a specific verb 'Compare' and identifies the resource 'ad performance metrics between two date ranges using attribution data.' It clearly distinguishes from sibling tools like hyros_best_performers by specifying the two-period comparison and the metrics returned (revenue, cost, ROAS, etc.). The example 'compare this week vs last week' further clarifies the purpose.

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

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

The description states prerequisites ('Requires an ad account ID and level') and describes what is returned (revenue, cost, ROAS, sales, leads, percentage changes). It also provides a typical use case ('Perfect for compare this week vs last week'). However, it does not explicitly mention when not to use this tool or suggest alternatives like hyros_best_performers for top-level summaries.

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 show readOnlyHint=false, confirming a write operation. However, the description only says 'register a call event' without disclosing side effects, required permissions, return behavior, or error handling. With no additional annotations, this is insufficient for a mutation 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 sentences, no wasted words. The first sentence defines the action, the second adds context. Front-loaded 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?

Despite 11 parameters and no output schema, the description does not explain success/failure signals, return values, or integration requirements. For a creation tool with many fields, more context is needed to ensure correct 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?

The input schema covers all 11 parameters with descriptions, achieving 100% coverage. The description adds no further parameter semantics, so baseline score of 3 is appropriate.

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

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

The description clearly states it registers a call event and links to ad sources. The verb 'create' and resource 'call' are specific, but it does not explicitly distinguish from sibling tools like hyros_update_call or hyros_create_lead.

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 for tracking sales calls and attribution, but provides no guidance on when to use this tool versus alternatives (e.g., hyros_update_call for editing, hyros_create_lead for lead creation). No exclusions or prerequisites are stated.

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 is consistent with annotations (readOnlyHint=false) but lacks details on constraints like uniqueness of cartId or side effects. Does not add behavioral context beyond the basic write 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 purpose and usage. No unnecessary words.

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

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

Given moderate complexity (9 parameters, no output schema), description is functional but lacks details on creation behavior, return value, and constraints.

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 high (67%), so description adds no extra meaning 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 the verb 'Create', resource 'cart', and context 'before it converts to an order'. It distinguishes from sibling tools like hyros_create_order and hyros_update_cart.

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

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

Explicitly says when to use: 'when a lead adds items to a cart'. However, it doesn't specify when not to use or mention alternatives like hyros_update_cart.

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=false, meaning mutation. The description adds 'manually track a click event' but no further behavioral details (e.g., idempotency, permissions, side effects). Since annotations carry the safety profile, the description contributes minimal extra transparency.

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

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

Two sentences, front-loaded with purpose and usage scenario. No wasted words, every sentence is informative.

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

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

Despite 15 parameters, the description is minimal and does not mention return values or success behavior. There is no output schema to compensate. For a creation tool, missing response details is a gap. Adequate but not comprehensive.

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 each parameter having a description. The description does not add semantic value beyond the schema; it only states the required parameter (referrerUrl). Baseline of 3 is appropriate as the schema already explains parameters.

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

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

The description clearly states the tool creates a click event for attribution purposes, with a specific verb ('create') and resource ('click event'). It distinguishes from sibling tools by specifying manual tracking for cases not automatically captured.

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 when you need to create a click record that was not automatically tracked', providing clear context. It does not explicitly mention when not to use or alternatives, but the context is strong enough to differentiate from automatic tracking.

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 readOnlyHint=false, confirming mutation. The description adds context on use cases but does not disclose behavioral details such as idempotency, side effects, or return values. With annotations present, a score of 3 is appropriate.

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

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

Two sentences with no fluff. The first sentence states the purpose, the second gives usage examples. Perfectly front-loaded and 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?

For a create tool with 6 parameters and no output schema, the description lacks information about return values, idempotency, or success indicators. It adequately explains the purpose but is not fully complete.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add extra meaning beyond the schema. Baseline 3 is correct.

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 'Add a custom ad cost in Hyros' with specific verb and resource. It distinguishes from siblings by specifying offline ad spend, influencer payments, or costs not auto-tracked. No ambiguity.

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

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

The description explicitly says when to use the tool (track offline ad spend, influencer payments, or costs not automatically tracked). It provides context but does not give explicit when-not-to-use guidance or alternatives, though siblings cover many other operations.

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 upsert behavior (update if email exists) which is beyond the simple 'create' annotation (readOnlyHint: false). It adds context about required fields and idempotency, but does not mention authentication, rate limits, or side effects. The description does not contradict annotations.

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

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

The description is two sentences long, directly states the main action and key constraint, with no extraneous information. It is front-loaded with the primary purpose.

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

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

Given the tool has 8 parameters and no output schema, the description lacks information about the return value (e.g., whether it returns the lead ID) and any potential errors. However, it covers the essential behavioral aspect (upsert). For a creation tool with moderate complexity, it is minimally adequate but has clear gaps.

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

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

The schema has 100% description coverage, but the description adds value by clarifying the mutual requirement of email and phoneNumbers ('At least one must be provided'), which is not explicitly stated in the individual parameter descriptions. This aids in understanding the parameter relationship.

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

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

The description clearly states the verb 'create' and the resource 'lead', with additional nuance about upsert behavior. It distinguishes itself from siblings like hyros_update_lead by specifying that an existing lead with the same email will be updated.

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 condition (at least one of email or phoneNumbers must be provided) but does not guide the agent on when to use this tool versus alternative tools such as hyros_update_lead or hyros_get_leads. No explicit when-to-use or when-not-to-use guidance is 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 indicate readOnlyHint=false, consistent with the description's 'creates' action. The description adds that the sale is 'attributed to a lead', providing some behavioral context beyond annotations, but does not disclose side effects, authorization needs, or rate limits.

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 brief, front-loaded sentences with no wasted words. Every sentence adds value, clearly stating the tool's purpose.

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

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

Given the complexity (10 parameters, no output schema), the description is minimal. It covers basic purpose but lacks operational context such as required lead identification (though schema handles it) or return information. Adequate but not comprehensive.

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 description does not need to add parameter details. The description adds no additional meaning beyond what the schema provides, meeting the baseline for high schema coverage.

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

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

The description clearly states 'Register a new sale/order' and 'creates a sale record', using a specific verb (register/create) and resource (sale/order). It distinguishes from sibling tools like hyros_refund_order (refund) and hyros_update_sale (update).

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 for creating orders but does not explicitly state when to use this tool versus alternatives or provide exclusions. It lacks guidance on prerequisites 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 indicate readOnlyHint=false, but the description does not add any behavioral context beyond that. It does not disclose idempotency, error handling, or side effects. For a mutation tool, more transparency is needed.

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

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

The description is a single, clear sentence with no unnecessary words. It is appropriately front-loaded 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?

Given no output schema, the description could mention return value or error conditions. However, for a simple create tool with few parameters, it is minimally complete but lacks guidance on what happens after creation.

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 does not add meaning beyond the schema. The baseline is 3 since the schema already explains parameters; the description provides no extra value.

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

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

The description clearly states the verb (Create), resource (product), and purpose (for sale attribution). It distinguishes this from sibling tools that create other entities like leads or orders.

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

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

No explicit guidance on when to use this tool versus alternatives or prerequisites. The description implies a straightforward creation task but lacks context like required authentication or typical usage 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 indicate readOnlyHint=false (write operation), which the description confirms with 'create'. However, the description does not disclose other behavioral traits such as what the tool returns, whether it requires specific authentication, or error conditions. With no output schema, this is a significant gap.

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 of 15 words, no wasted text. Front-loaded with purpose.

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

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

With 11 parameters and no output schema, the description is too brief. It does not explain parameter relationships (e.g., integationType vs trafficSource) or expected return value, leaving the agent underinformed.

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 each parameter has a description. The tool description adds 'for tracking custom marketing channels' but does not enhance understanding beyond schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Create' and the resource 'ad source/traffic source' in Hyros for tracking custom marketing channels. This distinguishes it from sibling tools like hyros_get_sources (read) and hyros_create_lead (different entity).

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. While the tool is unique among siblings, the description does not mention prerequisites or when not to use it, leaving implicit usage.

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

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

Annotations already indicate readOnlyHint=false, so the description adds no extra behavioral context. It does not disclose side effects, permissions, or what happens upon creation.

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

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

A single concise sentence that is front-loaded. However, for a tool with 14 parameters, slightly more detail could be added without losing conciseness.

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

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

Given the tool's complexity (14 parameters, no output schema), the description is minimal. It does not explain return values, error handling, or how this tool fits into a workflow.

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 adds no additional parameter-specific 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 uses a specific verb 'Register' and resource 'new subscription' clearly stating the action. It distinguishes from sibling tools like hyros_update_subscription or hyros_get_subscriptions.

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

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

The description provides no guidance on when to use this tool versus alternatives (e.g., hyros_update_subscription) or any prerequisites/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?

Beyond the annotation readOnlyHint=false, the description discloses a critical behavior: the returned secretKey is shown only once and must be surfaced to the user immediately. This is essential context for handling the tool's output and is not present in annotations or schema. No contradictions with annotations.

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

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

The description is two sentences, front-loaded with the primary purpose and followed by the critical secretKey detail. Every sentence earns its place with no redundant or fluff content.

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

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

For a create tool with no output schema, the description sufficiently covers the action, the one-time secretKey return, and the verification header. It does not explain error cases or prerequisites, but the schema provides parameter constraints (e.g., HTTPS URL). This is adequately complete 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 description coverage is 100%, so the parameters (name, targetUrl, eventTypes) are already well-documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides, matching the baseline for high schema coverage.

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

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

The description clearly states the tool's function: 'Subscribe an endpoint to Hyros events.' This is a specific verb+resource combination that distinguishes it from sibling tools like hyros_get_webhook_subscriptions (list) and hyros_delete_webhook_subscription (delete). The mention of returning a secretKey for verification further clarifies its purpose.

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 by saying 'Subscribe an endpoint to Hyros events,' but it does not explicitly state when to use this tool versus alternatives (e.g., when to list or delete subscriptions). No alternatives or exclusions are mentioned, so guidance is only implicit.

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

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

Annotations declare readOnlyHint=true, which the description aligns with. It adds behavioral context by listing the specific metrics returned (revenue, leads, calls, subscriptions), going beyond the annotation alone.

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 well-structured sentences with no wasted words. Every sentence adds value, clearly stating functionality and usage examples.

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

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

Without an output schema, the description compensates by listing the key return fields (revenue, leads, calls, subscriptions). It covers the essential context for an agent to use this tool effectively.

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

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds no new meaning beyond restating 'today (or a specific date)', which matches the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'complete performance summary' with specific details like revenue, leads, calls, and subscriptions. It distinguishes from sibling tools that fetch individual metrics.

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 with example questions like 'how did we do today?' but does not explicitly mention when to use alternatives or exclusions.

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

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

Annotations already indicate destructiveHint: true, so the description merely reinforces the destructive nature with 'Permanently delete.' No additional behavioral details (e.g., irreversibility, required permissions) are disclosed. The description does not contradict 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, clear sentence that is concise and front-loaded. However, it could include a brief warning about destructiveness without losing conciseness.

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

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

Given the tool's destructive nature, the description lacks completeness by not mentioning that the action cannot be undone or any potential side effects. There is no output schema, so the return behavior is entirely unspecified. Minimal information beyond the basics.

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 provides a description for the single parameter callId: 'Call ID to delete (required).' The description adds no further meaning, staying within the schema coverage. With 100% schema coverage, the description's contribution is neutral.

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 'Permanently delete a call record from Hyros,' specifying the exact verb (delete), resource (call record), and the permanent nature. It effectively distinguishes from sibling tools like create_call or get_calls.

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

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

No guidance is provided on when to use this tool versus alternatives. The description lacks information about prerequisites, context, or when not to use it. The sibling list is extensive but no differentiation is 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 declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to restate destructive behavior. It adds value by explaining the consequence: removing the cost prevents skewing profit and ROAS reports. 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 sentences, front-loaded with the action. Every word earns its place; no filler.

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

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

For a simple single-parameter delete tool with annotations, the description provides purpose, usage, and effect. It doesn't detail return values or permanent repercussions, but annotations and schema cover the essentials.

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 the single parameter 'id' with a description stating it comes from hyros_get_custom_costs. The description adds no further parameter semantics beyond what the schema provides, but with 100% schema coverage, 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 opens with 'Delete a custom cost,' which is a specific verb+resource pair. The added rationale about stopping mistaken or open-ended recurring costs distinguishes this from sibling get/create/update 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 sentence 'Use this to stop a mistaken or open-ended recurring cost from skewing profit and ROAS on every report' provides a concrete use case. It doesn't explicitly mention alternatives like hyros_update_custom_cost, but it implies when deletion is appropriate rather than editing.

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

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

The description adds significant context beyond annotations: it emphasizes permanence ('Cannot be undone'), mentions 'personal data' deletion, and links to legal frameworks. This goes beyond the destructiveHint=true annotation by explaining the real-world impact and data privacy implications.

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 deliver all essential information: what, how, when, and consequences. Zero waste, and the key message is front-loaded.

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

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

For a simple delete tool with only 2 optional parameters and no output schema, the description covers the purpose, usage context, and irreversibility. It doesn't describe return values, but that's expected for a delete operation. Could mention response behavior but not essential.

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

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

The schema already provides 100% coverage with both parameters described as 'Provide either email or id.' The description reinforces this but doesn't add new semantic details such as format or validation. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 verb 'permanently erase' with clear resource ('a lead'), and distinguishes it from sibling delete tools (hyros_delete_call, hyros_delete_sale) by specifying the target (lead) and the method of identification (email or id).

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

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

It explicitly states when to use (GDPR/CCPA right-to-erasure requests) and provides clear context that this is for permanent deletion. While it doesn't name alternatives or exclusions, the purpose is obvious and privacy-related. It could be improved by mentioning that other delete tools exist for other resource types, but the context is sufficient.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description consistently adds catalog scope and intended use. It doesn't add significant behavioral detail beyond that, so a 3 is appropriate.

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

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

The description is a single front-loaded sentence: first the action, then the usage note. Every word earns its place, 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?

For a simple delete tool with one parameter, strong annotations (destructive, idempotent), and no output schema, the description is sufficient. It explains what it does and when to use it, with no missing essential context.

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

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

The input schema fully documents the single 'id' parameter with a clear description and source (from hyros_get_products). The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly states the action (delete) and resource (product from Hyros catalog), and adds usage context (mistake/duplicate import), distinguishing it from sibling delete tools for other resources.

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

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

Provides clear context for when to use: removing a product created by mistake or duplicate import. However, it doesn't explicitly mention alternatives like hyros_update_product for corrective actions, so it stops short of a full 5.

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

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

The description adds 'permanently delete' and 'cannot be undone', which goes beyond the annotations (destructiveHint=true) by emphasizing irreversibility. No contradictions with annotations.

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

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

Two concise sentences with no wasted words. The core information is front-loaded.

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

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

For a simple delete operation with one required parameter and both annotations present, the description is fully adequate. It covers the action, permanence, and the required input.

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

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

Schema coverage is 100%, so baseline 3. The description does not add extra meaning beyond what the schema's description ('Sale ID to delete (required)') 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 verb 'delete' and the resource 'sale record', making the purpose unambiguous. It distinguishes itself from siblings like 'hyros_update_sale' and 'hyros_delete_call'.

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

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

No guidance on when to use this tool versus alternatives (e.g., update or other delete tools). No explicit when-not or alternative tools mentioned.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context that this is the irreversible option by highlighting the reversible alternative, going beyond the annotation's simple flags.

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

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

Three concise sentences cover action, use case, and alternative. Each sentence earns its place without any fluff or 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?

This is a simple single-parameter tool with annotations covering destructive/idempotent flags. The description covers purpose, usage, and alternative, leaving little ambiguity for a delete operation.

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

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

The schema defines 'tag' with 'Source tag, including the @ prefix', providing 100% coverage. The description does not add additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states 'Delete an ad source by its tag' with a specific verb and resource, and it distinguishes itself from sibling tools by focusing on deletion rather than other operations like update_source.

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 states when to use this tool ('clean up sources created by mistake that clutter every attribution pull') and names an alternative ('Setting isDisregard via hyros_update_source is the reversible alternative').

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

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

The description goes beyond the destructiveHint annotation by specifying that 'Deliveries stop immediately' and 'the secretKey is not recoverable afterwards.' This discloses critical irreversible consequences and timing of the delete operation. It also aligns with the idempotentHint annotation (deleting an already-deleted subscription could be considered idempotent). 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 two short sentences, with the action verb in the first word. It contains no filler or redundant statements. Every sentence adds essential information, making it exceptionally concise while still covering key behavioral details.

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

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

For a single-parameter delete tool with annotations for destructive/idempotent behavior, the description fully covers what happens (delete), how (by externalId), and consequences (immediate stop, secretKey loss). No output schema exists, so return values are not needed. The description is sufficiently complete 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?

The input schema provides 100% coverage with a clear description for externalId ('Subscription externalId (from hyros_get_webhook_subscriptions)'). The description repeats 'by its externalId' but adds no new syntax or format details beyond the schema. Therefore, the baseline score of 3 applies, as the schema carries the semantic load.

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

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

The description begins with 'Delete a webhook subscription by its externalId,' clearly stating the action (delete), resource (webhook subscription), and method (by externalId). This distinguishes it from sibling tools like hyros_create_webhook_subscription and hyros_get_webhook_subscriptions. The additional consequence 'Deliveries stop immediately' reinforces the purpose.

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 clearly implies when to use the tool: when you need to permanently stop webhook deliveries. It states the deletion is by externalId, and the schema description points to hyros_get_webhook_subscriptions for obtaining that ID. However, it does not explicitly mention alternatives or exclusions, so it lacks the explicit 'when-not' guidance that would earn a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds context that the tool calculates conversion rates and shows the customer journey stages. No contradictions, and the description adequately supplements the annotation's safety profile.

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 with the purpose front-loaded. Every sentence adds value: the first states the overall function, the second enumerates the specific metrics. 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?

While the description covers the main functionality and metrics, it lacks details about output format, pagination, or data limits. For a composite tool with multiple metrics and no output schema, more context would be beneficial to fully inform the 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 input schema has 100% description coverage for its 3 parameters, so the schema already explains them. The description adds value by implying the date range applicability and listing the metrics calculated, but does not provide additional parameter-specific details beyond the schema.

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

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

The description uses a specific verb ('Get') and resource ('complete funnel overview') and lists the exact metrics included (total leads, calls, sales, subscriptions, conversion rates). This clearly distinguishes it from sibling tools that focus on individual metrics.

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 for obtaining an aggregated funnel view over a date range, but does not provide explicit guidance on when to use this tool versus alternatives like hyros_get_leads or hyros_get_sales. No when-not or exclusion criteria are mentioned.

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

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

Annotations indicate readOnlyHint=true, so the description's 'get' aligns. However, the description adds minimal behavioral context beyond what annotations provide (e.g., no mention of rate limits or error handling).

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

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

Two concise sentences with no redundancy, effectively conveying the core purpose.

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

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

Given the complexity (16 parameters, no output schema), the description only covers high-level purpose. Lacks details on pagination, return format, or behavioral nuances, but schema is thorough.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema's parameter descriptions (e.g., 'ad account ID(s)' is already in schema).

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

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

Description explicitly states the action ('get'), resource ('attribution metrics grouped by ad account'), and scope, clearly distinguishing it from siblings like hyros_get_attribution_report.

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

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

No explicit guidance on when to use this tool versus alternatives such as hyros_get_attribution_report. The description only instructs to provide ad account IDs but does not exclude other 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 include readOnlyHint: true, so the safety profile is covered. The description adds valuable behavioral context by explaining that this tool returns the ids required by other report tools, effectively positioning it as a discovery prerequisite. It also lists the returned fields (id, name, platform), which enriches the behavioral understanding beyond the annotation.

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

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

The description is two sentences: the first front-loads the purpose and output, the second provides workflow guidance. There is zero fluff; every sentence earns its place. It's concise, scannable, and immediately informative.

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

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

For a simple list tool with no required parameters, no output schema, and read-only annotations, the description is complete. It explains what is listed, what fields are returned, and how to use it in relation to other tools. No critical information is missing given the tool's simplicity and the schema's full parameter coverage.

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

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

The input schema has 100% coverage with both parameters (ids, fields) already described clearly. The tool description does not add any extra meaning to the parameters themselves; it only mentions the output fields (id, name, platform), which is not parameter-related. Since the schema carries the full burden, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the ad accounts connected to Hyros with their id, name, and platform.' It uses a specific verb (List), specifies the resource (ad accounts connected to Hyros), and even mentions exact output fields. It also distinguishes itself from sibling report tools by stating it should be called first to discover ids needed by hyros_get_ad_account_report and hyros_get_attribution_report.

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 instructs when to use the tool: 'Call this first to discover the ids that hyros_get_ad_account_report and hyros_get_attribution_report need.' This gives clear context and a prerequisite workflow. However, it does not explicitly state when not to use it or mention alternative tools, so it stops short of a perfect 5.

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

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

The readOnlyHint annotation already indicates a safe read operation. The description adds no further behavioral details (e.g., pagination, ordering, or rate limits), so it provides minimal additional value beyond the annotation.

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

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

The description is a single concise sentence with no filler, front-loading the key action. It could be slightly more informative without becoming verbose, but it remains efficient.

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

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

Given the absence of an output schema, the description could mention what data the tool returns (e.g., ad details). It also does not clarify the scope of 'ads' or any relationship to other tools. It is adequate but not comprehensive.

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

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

Schema coverage is 100%, so the description is not required to elaborate on parameters. It loosely references the integrationType by mentioning 'specific advertising platform', but this does not significantly add meaning beyond the schema.

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

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

The description clearly states the verb 'Get' and the resource 'ads', and adds context about filtering by a specific advertising platform. This distinguishes it from sibling tools like hyros_get_leads or hyros_get_sales.

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 the need for an integrationType parameter but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention any prerequisites 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?

The annotations already provide readOnlyHint=true. The description adds no further behavioral context (e.g., performance, data volume, pagination limits). It does not contradict annotations.

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

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

The description is only two sentences, front-loaded with the core purpose, and each sentence adds value without redundancy.

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

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

Given the high parameter count (15) and no output schema, the description covers the main use case but omits details on optional parameters like pagination, filters, and grouping. It is adequate but not comprehensive.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the need for level and IDs but adds no new semantic 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 retrieves attribution metrics for ads, campaigns, or ad sets, and provides example questions. It distinguishes itself from sibling tools like hyros_get_sources by referencing the need to use that tool first.

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

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

The description explicitly tells when to use the tool (answering ROAS, ROI questions) and advises to use hyros_get_sources first. It does not explicitly state when not to use it, 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.

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

Annotations already indicate readOnlyHint=true, so the description carries a lower burden. However, it merely restates filterable fields from the schema and adds no new behavioral details like pagination behavior, rate limits, or default result ordering.

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

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

Two sentences, each providing value: the first states the core purpose, the second adds context and filter hints. No redundant or extraneous content.

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

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

Despite 10 optional parameters and no output schema, the description omits critical details like pagination (pageId, pageSize), default behavior when no filters are applied, and the return format. This inadequately prepares an agent for effective 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 coverage is 100%, providing baseline of 3. The description groups parameters by category (date, email, qualification, call state) but does not add syntactic or relational meaning beyond the schema's individual 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 verb 'retrieve' and resource 'call records', distinguishing it from sibling tools like hyros_get_leads or hyros_get_sales. The additional context about phone sales teams reinforces the tool's domain.

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

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

The description provides a usage hint ('useful for businesses with phone sales teams') and lists filter options, but does not explicitly state when to avoid this tool or suggest alternative tools among the many 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?

The annotation already declares readOnlyHint=true, so the safety profile is known. The description adds a behavioral note about the 'purchased' parameter's effect on filtering, helping the agent understand how to target abandoned carts. 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 two short sentences, front-loaded with the action and entity. Every word adds value—the second sentence directly instructs a useful filter combination.

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

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

The tool is a simple filtered list operation with no required parameters. The schema fully documents all parameters, and the description provides a practical use case. The lack of an output schema is acceptable for a list tool of this nature, matching high-caliber examples.

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

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

The input schema already documents all 7 parameters with descriptions covering 100% of the schema. The description reinforces the 'purchased' parameter's semantics with an example, but does not add new information beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses the specific verb 'List' with a clear resource 'shopping carts', and explicitly mentions the filtering dimensions (purchase status, lead, date). This distinguishes it from sibling tools like hyros_get_sales and hyros_get_leads, which focus on different entities.

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

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

The description gives a concrete use case (Set purchased=false to find abandoned carts for a recovery campaign), indicating when the tool is useful. However, it does not explicitly mention alternatives or exclusions, so it stops short of full when/when-not guidance.

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

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

The description aligns with readOnlyHint=true, indicating a read operation. It adds context about ad clicks and traffic sources but does not disclose additional behavioral details 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 a single clear sentence with no unnecessary words, making it highly concise and front-loaded.

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

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

The description covers the core purpose and mentions relevant context (ad clicks, traffic sources). While it omits pagination and date parameters, the schema fully documents these, so the combination is complete.

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

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

Schema coverage is 100% with well-described parameters. The description does not add significant meaning beyond what the input schema already provides, matching 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 it retrieves click tracking data for a specific lead, which is a specific verb+resource combination. It distinguishes itself from siblings like hyros_create_click and other get 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 implies usage for retrieving clicks for a specific lead but does not explicitly state when not to use or mention alternatives. It provides basic context but lacks guidance on 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?

The readOnlyHint annotation already establishes the read-only nature, and the description adds behavioral context about the date-window filtering and recurring-cost edge case. No contradiction exists, and the extra context is valuable.

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 with an action-first verb, concrete examples, and a clear use case. No redundancy or filler, making it appropriately sized and front-loaded.

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

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

For a simple read tool with full schema coverage and no output schema, the description covers purpose, examples, and use case. It does not mention pagination behavior, but that is available in the schema and not critical for this 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 descriptions cover 100% of parameters, including detailed semantics for fromDate. The description mentions 'date window' but does not elaborate on individual parameters, so it adds minimal value 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 opens with 'List custom costs', a specific verb and resource, and adds clarifying examples (agency fees, tool subscriptions, offline spend) and a date-window scope. This clearly differentiates it from sibling tools like get_calls or get_leads.

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 second sentence gives explicit use-case guidance: 'Use this to audit costs that skew profit and ROAS, especially recurring ones left without an end date.' It lacks explicit alternatives or 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?

The annotation readOnlyHint already signals non-destructiveness. The description adds that domains are 'verified' but does not disclose other behaviors like return format or rate limits.

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 with no wasted words, directly stating the tool's function.

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?

Adequate for a simple read-only tool without parameters, though missing output details could be improved for full completeness.

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 0 parameters and high schema coverage, the description adds value by clarifying the scope ('verified domains') beyond the empty 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 'Get all verified domains in your Hyros account' uses a specific verb and resource, clearly distinguishing it from other get tools like hyros_get_user_info or hyros_get_calls.

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

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

No guidance on when to use this tool versus alternatives; lacks context such as prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the description does not need to repeat that. It adds the Google Ads context but no further behavioral details (e.g., rate limits, scope). Sufficient for a read operation given 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?

Single sentence, no fluff, front-loaded with the action and resource. Every word 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 tool with one required parameter and no output schema, the description is mostly complete. It could hint at return format, but that is less critical 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?

The schema covers the single parameter adgroupId with description. The description reiterates 'specific ad group' but adds no new semantic detail. Baseline score since schema coverage is 100%.

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 (get) and resource (keywords for a specific ad group), and hints at the Google Ads context. It distinguishes from siblings like hyros_get_ads or hyros_get_clicks by specifying the resource, though no explicit differentiation.

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 other keyword-related tools or alternatives. The Google Ads hint is the only usage context, but lacks explicit when-to-use or when-not-to-use information.

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, establishing the read-only nature. The description adds behavioral details beyond annotations: it returns multiple journey components (sales, calls, etc.) and accepts emails directly. It does not disclose response format or potential limitations, but with annotations covering safety, this is sufficient.

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

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

The description is two concise sentences: the first states the function and data components, the second gives a use case and input flexibility. It is front-loaded with no filler or repetition.

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

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

The tool has 3 optional parameters and no output schema. The description explains the purpose, the contents of the journey, and when to use it, which is adequate for tool selection and basic invocation. It could mention response shape or pagination, but the listed components give a reasonable expectation.

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

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

Schema description coverage is 100%, so the schema already documents ids, emails, and includeEvents thoroughly. The description reinforces email acceptance but does not add new parameter-level syntax or semantics. Baseline 3 is appropriate when the 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 uses the specific verb 'Get' with a clear resource: 'complete customer journey for one or more leads,' and enumerates components (sales, calls, carts, subscriptions, linked leads, ad attribution sources). This distinguishes it from sibling tools that focus on individual data types.

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 specific use case: 'Use this to understand what ads drove a customer to convert.' It also implies a workflow advantage by stating 'Accepts emails directly, so no lookup round-trip is needed.' However, it does not explicitly name alternative tools or exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, and the description aligns with that. Beyond annotations, the description/schema notes important behavioral traits: tags/stages match on ANY, phone matches trailing digits and only finds leads with an email, and updatedFromDate enables incremental sync (unlike join-date filters). These add valuable context beyond the read-only hint.

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

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

The description is two sentences, front-loaded with the core action and filters, followed by use cases. Every phrase earns its place, with no redundancy or fluff.

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

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

Given 11 parameters, no required params, and no output schema, the description covers the essential use cases and leaves param details to the schema (which is exhaustive). It doesn't explicitly mention pagination or filter combination, but the schema handles pagination via pageId/pageSize, making the description adequate for a read-only search tool.

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

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

Schema description coverage is 100%, with rich per-parameter details (max limits, examples, matching semantics). The description only summarizes filter types ('email, phone, tag, stage, join date, last-updated') without adding new meaning. This is exactly the baseline 3 case where the schema carries the weight.

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 ('Search and retrieve leads from Hyros'), names the specific resource (leads), and enumerates the filter dimensions (email, phone, tag, stage, join date, last-updated). This distinguishes it from sibling tools like hyros_get_lead_journey, which focuses on a lead's journey rather than search/retrieval.

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 usage context: 'Use this to find customers, check their tags and current funnel stage, and sync changes into another system.' This tells the agent when the tool is appropriate, but it does not explicitly name alternatives or exclusions, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it is safe and non-destructive. The description adds context about the purpose and that it returns pricing data, but it does not disclose pagination behavior, default result sizes, or the exact response shape. This is adequate given the read-only annotation, but not rich.

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, and no unnecessary words or repetition. The use cases are appended succinctly. This is highly 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?

The tool has 6 optional parameters, pagination support, and no output schema. The description explains the purpose and use cases, but it does not mention that results are paginated, whether all products are returned when no filters are provided, or the structure of the response. Given the absence of an output schema, this is a notable gap, though the read-only nature and good schema coverage keep it acceptable.

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% parameter description coverage, so the schema already explains each parameter. The description does not add any additional semantics beyond what the schema provides, such as examples, formatting rules, or relationships between parameters. Baseline 3 is appropriate.

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

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

The description clearly states the action ('List products in the Hyros catalog') and identifies the resource and specific returned fields (price, cost of goods, category). This distinguishes it from sibling getters such as get_sales or get_leads, and from product mutation tools like create_product.

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

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

The description provides explicit use cases: 'Use this before creating a product to avoid duplicates, or to audit the pricing that feeds profit and ROAS reporting.' It clearly indicates when to use the tool, though it does not mention 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?

Annotations already declare readOnlyHint=true, and the description aligns with a read operation. No contradictions. The description adds behavioral context (date range, status filters) but omits pagination behavior. However, given annotations cover safety, further detail is not critical.

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, no wasted words. The first sentence clearly states the action and filters; the second provides use cases. Efficient 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?

Despite no output schema, the description hints at output content (revenue, products, refunds). Parameter count is high but all optional, and the description covers the main filter categories. Slight omission of pagination details, but adequate for a read-only 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?

Since schema description coverage is 100%, the baseline is 3. The description adds value by grouping parameters into conceptual categories (date, email, lead ID, product tag, recurring/refund status), which helps the agent understand the tool's capabilities beyond the raw schema.

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

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

The description uses a specific verb ('Retrieve') and resource ('sales records'), lists multiple filter options, and explicitly states use cases (check revenue, see products sold, track refunds). Distinguishes from sibling mutation tools like hyros_refund_order and hyros_delete_sale.

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

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

The description provides clear use cases (check revenue, product sales, refunds) but does not explicitly mention when NOT to use this tool or suggest alternative tools for specific needs. Still, the context is adequate for selecting the tool.

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

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

Description adds minimal beyond the readOnlyHint annotation. No mention of pagination, rate limits, or default behavior. For a tool with 6 optional parameters, more behavioral context is needed.

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

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

Two sentences, no fluff. Every word earns its place.

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

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

With 6 optional parameters and no output schema, the description is too minimal. It does not explain return format, pagination, or how filters combine with the hierarchy of sources/campaigns/ad sets.

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

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

Schema coverage is 100%, so the description does not need to add much. The description provides a general overview but no additional detail beyond what the schema already describes.

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

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

The description clearly states the verb 'Get' and resource 'ad sources and campaigns', and explains what sources represent. However, it does not differentiate this tool from siblings like hyros_get_ads or hyros_get_clicks.

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. Lacks information about prerequisites or use cases.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. It adds examples of common stage names, which provides context beyond the annotation, but does not disclose pagination behavior or any potential side effects. Overall, it offers a modest addition to the annotation.

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

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

The description is a single, efficient sentence that front-loads the primary purpose. All words are necessary, and there is no repetition. It is appropriately brief while being informative.

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

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

Despite full schema coverage and readOnlyHint, the description does not describe the response format (e.g., whether it returns a list of objects with IDs and names) or clarify the pagination behavior indicated by the parameters. This leaves the agent without crucial information for processing results. The description should compensate for the missing output schema.

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

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

Schema coverage is 100% with each parameter described in detail. The description adds no extra meaning to the parameters (name filter, pagination IDs, page size). With high coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'all lead funnel stages' with concrete examples (MQL, SQL, Opportunity, Customer). It is unambiguous and distinguishes itself from sibling tools, none of which retrieve funnel stages.

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 the context of retrieving configured stages but lacks explicit guidance on when to use this tool versus alternatives, or when not to use it. Since no sibling tool retrieves stages, the omission is minor, but the dimension expects some usage direction.

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

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

Annotations declare readOnlyHint=true, so description doesn't need to reiterate safety. Description adds that it retrieves records and specific uses, but does not disclose behavioral details like pagination, rate limits, or response format. Adequate but minimal extra value.

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

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

Two concise sentences with no redundant information. Every word contributes to 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 9 optional parameters and no output schema, the description gives a high-level purpose but doesn't explain return structure, pagination behavior, or how the filters interact. Somewhat incomplete for a complex query 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 description coverage is 100%, so the schema already documents all parameters. The description adds no additional semantic meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description uses specific verb 'Retrieve subscription records' and lists concrete use cases (MRR, active subscribers, churned customers, status changes). It clearly distinguishes from sibling tools, which are create/update/delete or for other 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 implies usage by listing what you can do (check MRR, see active subscribers, etc.), but does not explicitly state when to use this tool over alternatives or provide exclusions. However, given the sibling list, its role as the primary read subscription tool is clear.

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

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

Annotations already declare readOnlyHint=true, so the description goes beyond by explaining tag prefix conventions ($ product, @ source, ! action) and the deprecation status. This adds useful behavioral context without contradicting the annotation.

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

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

Three concise sentences, each earning its place: the core action, tag naming semantics, and deprecation guidance. Information is front-loaded and no unnecessary text remains.

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 parameterless list tool with no output schema, the description gives sufficient context: what is returned (flat list), how to interpret tag prefixes, and the recommended replacement. It is fully adequate for an agent to select and invoke the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description enriches understanding by detailing the meaning of tag prefixes, which is more than the empty schema provides.

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

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

The description clearly states it retrieves all available tags in the Hyros account as a flat list, with specific verb and resource. It differentiates itself from the sibling tool hyros_get_tags_count by noting deprecation and the alternative's additional features.

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 advises that this tool is deprecated in favour of hyros_get_tags_count, which adds lead counts and pagination. This gives unambiguous guidance on when not to use this tool and what to use instead.

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 annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the tool returns counts per tag, which is useful behavioral context. However, it does not disclose additional details like pagination mechanics or error behavior, so it adds moderate value but not rich context.

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

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

The description is two sentences with no fluff. The first sentence states the core function, the second gives targeted guidance about alternatives. Every word earns its place.

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

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

For a read-only tool with 3 optional parameters and no output schema, the description covers purpose, usage, and the alternative. It implies return structure ('how many leads carry each one') and the schema covers parameter details. It lacks explicit pagination-flow or edge-case handling, but overall it is complete enough for a simple 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 description coverage is 100% and parameter descriptions are detailed (e.g., exact name, prefix, partial names). The tool description adds meaning by mapping parameter use cases ('sizes' to counts, 'pagination' to pageId/pageSize, 'look up one tag' to name), which helps an agent understand when to supply each parameter.

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

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

The description uses a specific verb+resource ('List tags along with how many leads carry each one') and explicitly differentiates from the sibling tool hyros_get_tags by describing when to use this one instead. This clearly states the tool's purpose and distinguishes it from the most similar alternative.

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 'Use this instead of hyros_get_tags when you need sizes, pagination, or to look up one tag.' This names the alternative tool and provides clear conditions for when to use this tool, fulfilling the when-to-use guidance perfectly.

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, indicating a safe read operation. The description adds no extra behavioral context beyond that, but does not contradict annotations.

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

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

Single sentence that is concise and front-loaded. Could benefit from slightly more detail without losing conciseness, but it is efficient and gets the main point across.

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 is minimal. Given there is one optional parameter and no output schema, it provides basic understanding but lacks details on output format, when to use 'domain', or any edge cases. Adequate but with clear gaps.

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

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

Schema coverage is 100% with one optional parameter 'domain' described in the schema. The description does not add any additional meaning or usage hints for the parameter beyond what the schema provides.

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

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

The description clearly states the verb 'Get', the resource 'Hyros tracking script', and the purpose 'to install on your website'. It is specific and distinguishes from sibling tools which also use 'get' but for different resources.

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. It does not mention prerequisites, when not to use it, or any context for choosing between this and other 'get' 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?

The description is consistent with annotations (readOnlyHint true) and adds value by specifying the return data. It fully informs the agent of the read-only, safe nature without contradictions.

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

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

The description is a single, well-structured sentence with all necessary information front-loaded. No redundant 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?

The description covers the return data sufficiently, but lacks mention of potential error cases or authentication scope. However, for a simple get tool, 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?

The tool has no parameters and schema coverage is 100%. The description adds meaning by listing the returned fields, meeting the baseline for zero-parameter tools.

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 gets authenticated Hyros account information and specifies the data fields (email, timezone, currency). It distinguishes well from sibling tools which focus on other entities like leads, sales, or calls.

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

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

The description implicitly tells when to use the tool (when account info is needed), but does not explicitly state when not to use it or mention alternatives. However, given the unique function among siblings, this is adequate.

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 adds context about the content of the response (target URL, subscribed events, delivery state) beyond the readOnlyHint annotation, which is useful since there is no output schema. 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 sentences, front-loaded with the action, no filler. Directly communicates both what and why.

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

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

For a simple list operation with no parameters and readOnlyHint, the description covers purpose, result content, and a usage scenario. It lacks mention of pagination or error cases, but these are not critical for this simple 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?

There are zero parameters, so the description is not required to explain parameter details. The baseline of 4 applies as the schema is complete (empty).

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?

States the specific action 'List' and resource 'webhook subscriptions' with account scope. Clearly distinguishes from create/delete webhook subscription tools by focusing on existing subscriptions.

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

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

Provides a clear use case ('audit which systems receive Hyros events') that informs when to use it, but 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's 'Process a refund' is consistent. However, it adds no further behavioral details such as irreversibility, effect on related data, or error conditions.

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 key action. Every word is purposeful, with no redundancy or filler.

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

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

The tool is simple with two parameters and no output schema. The description explains the core function but omits what the tool returns on success or failure, leaving the agent to infer behavior.

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

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

Both parameters are fully described in the schema (100% coverage). The description adds that omitting refundedAmount results in a full refund, which provides useful nuance 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 'Process a refund for an existing order,' specifying the verb (refund) and resource (order). It is distinct from sibling tools like create/update/delete, making its purpose unambiguous.

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

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

The description implies this tool is for refunding orders, but it lacks guidance on when to use it versus alternatives, prerequisites (e.g., order must exist), 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 already indicate readOnlyHint=true, so the description does not need to repeat safety traits. It adds context about the report's contents (metrics), but does not disclose any additional behavioral traits such as authentication needs, rate limits, or data freshness. With annotations covering read-only, this is adequate but minimal extra value.

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

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

The description is concise, consisting of two efficient sentences. The first sentence states purpose and lists key metrics; the second provides example queries. It is front-loaded with the action and key output. Minor improvement could be structuring the list of metrics more clearly, but overall it earns its space.

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

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

With no output schema, the description compensates by listing the main metrics (active count, MRR, etc.). However, it does not explain how the optional parameters (date range, currency) affect these metrics, nor does it describe the structure of the response (e.g., single object vs. array). This leaves some ambiguity for an agent trying to parse the 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?

All three parameters (toDate, currency, fromDate) are fully described in the input schema (coverage 100%). The description adds no further meaning about these parameters, such as how they affect output or examples. Baseline is 3 for high schema coverage.

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

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

The description clearly states 'Get a health report for your subscription business' and lists specific metrics (active count, MRR, etc.). It uses a specific verb and resource, and the examples ('what is my MRR?') help clarify purpose. However, it does not explicitly differentiate from the sibling 'hyros_get_subscriptions' which may return raw subscription data, leaving some ambiguity.

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

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

The description provides 'Perfect for' examples that imply use cases (MRR, active subscribers). However, it does not specify when not to use this tool (e.g., when raw subscription data is needed) or mention alternatives such as 'hyros_get_subscriptions'. The guidance is implicit and lacks explicit exclusions.

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

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

The description aligns with annotations (readOnlyHint=false, idempotentHint=true) by indicating an update operation. However, it lacks details on required permissions, error handling, or side effects beyond stating the fields updated.

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 brief, single sentence, front-loading the key action. While concise, it could expand slightly to cover more parameter interactions without significant bloat.

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

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

With five parameters including a boolean qualification and an enum state, the description does not explain how these fields relate or interact. No return value is described, and the tool could benefit from additional context on usage patterns.

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 input schema already defines each parameter. The description adds no further parameter-level meaning beyond the high-level purpose, which is adequate.

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 updates the qualification status or state of existing call records, which distinguishes it from create/delete siblings. However, it does not mention the ability to update other fields like name or externalIds, limiting full scope clarity.

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 for updating existing call records but provides no explicit guidance on when to use this tool versus alternatives (e.g., create_call, delete_call). No when-not or prerequisite information is 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=false and idempotentHint=true, so the description's statement 'Update' is consistent but adds no extra behavioral detail (e.g., safety, prerequisites). It does not contradict annotations.

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

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

Two concise sentences: first states action, second provides usage context. All information is relevant and front-loaded with no wasted content.

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

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

Given 9 parameters, no output schema, and annotations providing idempotency, the description covers usage but omits return values, error handling, and prerequisites (e.g., cart must exist and not be converted). Adequate but not thorough.

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

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

Schema description coverage is 67%, meaning some parameters lack descriptions. The description groups parameters as 'items or customer info' but does not fully compensate for undocumented fields like leadIps or phoneNumbers.

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

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

The description clearly states the verb 'Update' and resource 'cart' and adds specific context (pending cart before conversion), distinguishing it from sibling tools like hyros_create_cart.

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 this to modify items or customer info on a pending cart before it converts to an order,' providing clear context. It does not explicitly exclude scenarios but adequately guides when to 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 a critical behavioral trait beyond the annotations: 'The whole cost is replaced, so send every field, not only the ones changing.' This is important for correct invocation and is not captured in the readOnlyHint/idempotentHint annotations. It also explains the endDate use case, adding practical context.

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

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

The description is two sentences long, front-loaded with the core action, and every clause adds value: the action, the replacement warning, and the use cases. No redundant or vague phrasing.

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

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

Given no output schema and sparse annotations, the description covers the essential operational context: what the tool does, the replacement semantics, and when to use it. It lacks return-value or error-behavior details, but for an update operation with a rich schema, this is adequate. Slightly more info on request results could push it to 5.

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 provides full descriptions for all 7 parameters (100% coverage), so the description doesn't need to explain individual parameters. It does add contextual guidance about sending every field due to replacement semantics, but this is more about overall operation behavior than specific parameter meaning.

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 'Update a custom cost' with a specific verb and resource, and it distinguishes itself from sibling create/get/delete tools by presenting concrete use cases (fixing a wrong amount, closing an open-ended recurring cost).

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 the tool ('Use this to fix a wrong amount or to close an open-ended recurring cost by setting endDate'), which gives clear guidance for typical scenarios. However, it does not explicitly mention alternatives like create/delete for non-update cases, though sibling names make that implicit.

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 this as a write operation (readOnlyHint=false) and idempotent (idempotentHint=true). The description adds the search-parameter requirement and the set of updatable fields, but doesn't disclose other side effects like permanent changes or error behavior when no lead matches. Given annotations cover the safety profile, the description provides moderate additional context.

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

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

The description is three concise sentences, front-loaded with the action, then the key requirement, then the scope. No filler or repetition of schema property descriptions.