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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read-only operation ('Get') and mentions checking balance, which suggests non-destructive behavior, but lacks details on authentication needs, rate limits, or error handling. The description adds some context but is incomplete for a tool with no 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 highly concise and well-structured, consisting of two sentences that efficiently convey purpose and usage guidelines without any wasted words. It is front-loaded with the core functionality and follows with practical application advice.

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

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

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is largely complete for its purpose. It covers what information is retrieved and when to use it, though it could benefit from more behavioral details like response format or error cases. The absence of an output schema means some gaps remain in understanding the return values.

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

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

The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description does not add parameter semantics, but this is appropriate as there are no parameters to explain. A baseline of 4 is applied since the schema fully covers the absence of 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's purpose with specific verbs ('Get') and resources ('Barevalue account information'), listing detailed components like credit balance, AI subscription status, bonus minutes, and pricing. It effectively distinguishes this read-only informational tool from siblings that handle actions like submitting orders or managing webhooks.

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 provides usage guidance by stating 'Use this to check available balance before submitting orders,' which directs when to use this tool (for pre-order checks) and implies alternatives like order submission tools (e.g., barevalue_submit) for different actions. This offers clear context and exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool returns a cost breakdown, which is useful, but does not cover other behavioral aspects like error handling, rate limits, authentication requirements, or whether it performs any side effects (e.g., creating a draft order). This leaves gaps in transparency for a tool that likely interacts with order data.

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

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

The description is front-loaded and highly concise, consisting of two sentences that efficiently convey the tool's purpose and output. Every sentence earns its place by providing essential information without redundancy or unnecessary detail.

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

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

Given the tool's moderate complexity (cost calculation with one parameter) and lack of annotations or output schema, the description is reasonably complete. It explains the purpose, usage context, and output breakdown, but could be more comprehensive by detailing behavioral traits or error scenarios, which slightly limits 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?

The schema description coverage is 100%, with the parameter 'duration_minutes' fully documented in the schema. The description does not add any additional semantic information about the parameter beyond what the schema provides (e.g., why duration matters for cost calculation), so it meets the baseline score of 3 without compensating 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 specific action ('Calculate the cost'), resource ('AI podcast editing order'), and scope ('before submission'), distinguishing it from siblings like barevalue_submit (which submits orders) and barevalue_list_orders (which lists existing orders). It explicitly mentions what the tool does rather than restating the name.

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

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

The description provides clear context for when to use this tool ('before submission'), implying it should be used prior to submitting an order. However, it does not explicitly state when not to use it or name alternatives (e.g., barevalue_submit for actual submission), which prevents a perfect score.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions listing 'recent orders' but doesn't specify what 'recent' means (timeframe), whether results are paginated (implied by parameters but not stated), authentication requirements, rate limits, or error behaviors. The description adds minimal behavioral context beyond the basic 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?

The description is two concise sentences with zero waste: the first states the core purpose, and the second provides usage context. It's appropriately sized and front-loaded, with every sentence earning its place by adding value.

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

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

Given 3 parameters with full schema coverage but no annotations or output schema, the description is minimally adequate. It covers the basic purpose and usage but lacks details on behavioral traits (e.g., pagination, 'recent' definition, error handling) that would help an agent use it correctly. For a list operation with no output schema, more context on return format would be beneficial.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (page, per_page, status) with descriptions and constraints. The description doesn't add any parameter-specific semantics beyond what's in the schema, such as explaining the 'status' enum values or pagination behavior. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb 'List' and resource 'recent orders with their status', making the purpose specific and understandable. It distinguishes from siblings like 'barevalue_submit' (creation) and 'barevalue_status' (single status check) by focusing on listing multiple orders. However, it doesn't explicitly contrast with 'barevalue_webhooks_list' which might also list items.

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 implied usage context: 'Useful for checking on multiple orders or finding a specific order.' This suggests when to use it (bulk checking/searching) but doesn't explicitly state when NOT to use it or name alternatives like 'barevalue_status' for single-order checks. No prerequisites or exclusions 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's read-only nature (checking status) and output behavior (returning processing state and download URLs), but doesn't mention potential limitations like rate limits, authentication needs, or error conditions. It adds useful context about what information is returned but could be more comprehensive.

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

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

The description is perfectly concise and well-structured in a single sentence that front-loads the core purpose and follows with important return value details. Every word earns its place with no redundancy or unnecessary elaboration, making it highly efficient for agent comprehension.

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

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

Given the tool's moderate complexity (single parameter read operation), no annotations, and no output schema, the description does a good job of explaining what the tool returns. However, it could be more complete by mentioning potential error cases or clarifying the format of the 'processing state' return value. The description compensates well for the lack of output schema by detailing return types.

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 description coverage is 100%, with the single parameter 'order_id' well-documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, which is acceptable given the high schema coverage. The baseline of 3 is appropriate when the schema does the heavy lifting for 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 clearly states the tool's purpose with specific verb ('Check') and resource ('status of an order'), distinguishing it from siblings like barevalue_list_orders (which lists orders) and barevalue_submit (which submits orders). It precisely identifies what the tool does without being vague or tautological.

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

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

The description implies usage context by mentioning 'when complete' and listing output types, but doesn't explicitly state when to use this tool versus alternatives like barevalue_list_orders for order overviews. It provides some guidance through the return value details but lacks explicit when/when-not instructions or named alternatives.

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

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

With no annotations provided, the description carries full burden. It discloses important behavioral traits: that the operation 'charges credits/subscription minutes' (cost implication) and requires specific inputs from another tool. However, it doesn't describe what happens after submission (processing time, notifications, error handling) or authentication requirements, leaving significant gaps 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, zero waste. First sentence states the core purpose and cost implication. Second sentence specifies prerequisites. Every word serves a clear function. The description is appropriately sized and front-loaded with the most critical information.

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

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

For a mutation tool with 9 parameters, no annotations, and no output schema, the description provides adequate basic context about purpose and prerequisites but lacks important behavioral details. It doesn't explain what the tool returns, how long processing takes, error conditions, or authentication requirements. Given the complexity and lack of structured data, it should do more to be complete.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly. The description mentions order_id and s3_key as required inputs from barevalue_upload, adding minimal context about their source but no additional semantic meaning beyond what the schema provides. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the specific action ('submit an uploaded audio file for AI podcast editing'), identifies the resource ('uploaded audio file'), and distinguishes from siblings by specifying it's for files uploaded via barevalue_upload (unlike barevalue_submit_url). It provides a complete purpose statement with 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?

Explicitly states when to use this tool ('submit an uploaded audio file') and provides clear prerequisites ('requires order_id and s3_key from barevalue_upload'). It distinguishes from barevalue_submit_url by specifying it's for uploaded files rather than URLs. The description effectively guides the agent on proper usage context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that 'The file will be downloaded and processed,' which implies a write/mutation operation (submitting for editing) and gives some context about the workflow. However, it lacks details on permissions, rate limits, response format, or what 'AI editing' entails, leaving gaps for a tool with significant functionality.

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 appropriately sized and front-loaded: the first sentence states the core purpose, the second explains the process, and the third provides usage context. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

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 (8 parameters, mutation operation) and lack of annotations or output schema, the description is moderately complete. It covers the purpose and usage context but misses behavioral details like response format, error handling, or editing outcomes. For a tool that initiates AI processing, more context on what to expect would be beneficial.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., it doesn't explain URL formats beyond 'public URL' or elaborate on processing styles). With high schema coverage, the baseline is 3, as the description doesn't compensate with extra insights.

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 specific action ('Submit a podcast for AI editing') and resource ('using a public URL'), distinguishing it from sibling tools like barevalue_submit (which likely uses different input methods) and barevalue_upload (which might involve direct file uploads). It explicitly mentions the download and processing steps, making the 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 provides clear context for when to use this tool ('Useful for files hosted on Dropbox, Google Drive (with public link), or other file hosting services'), indicating it's for public URLs rather than direct uploads. However, it doesn't explicitly state when NOT to use it (e.g., vs. barevalue_submit or barevalue_upload) or name specific alternatives, which prevents a perfect score.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it handles getting a presigned S3 URL and uploading the file, returns order_id and s3_key for submission, and specifies a maximum file size of 750MB. This covers critical operational details like the two-step process and output format, though it could add more on error handling or authentication needs.

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

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

The description is highly concise and front-loaded, with three sentences that each add value: stating the purpose, detailing the process, and specifying constraints. There is no wasted text, and it efficiently communicates essential information without redundancy, making it easy for an agent to parse quickly.

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

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

Given no annotations and no output schema, the description provides good context for a file upload tool: it explains the process (S3 URL handling), output (order_id and s3_key), and constraints (file size). However, it could be more complete by mentioning authentication requirements, error scenarios, or how the output integrates with sibling tools like barevalue_submit, leaving minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (file_path and filename) thoroughly. The description does not add any parameter-specific semantics beyond what the schema provides, such as explaining why filename is optional or detailing file format implications. Baseline 3 is appropriate as 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 clearly states the specific action ('upload an audio file for AI podcast editing') and distinguishes it from siblings like barevalue_submit or barevalue_list_orders by focusing on file upload with S3 integration. It specifies the resource (audio file) and the purpose (AI podcast editing), making it distinct and unambiguous.

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

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

The description implies usage when uploading audio files for podcast editing, but does not explicitly state when to use this tool versus alternatives like barevalue_submit_url or barevalue_validate. It mentions the maximum file size (750MB) as a constraint, but lacks guidance on prerequisites, error conditions, or comparisons with sibling tools, leaving some ambiguity for the agent.

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

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

With no annotations, the description carries full burden and effectively discloses key behaviors: it's a pre-check validation tool (non-destructive), does not charge credits (cost implication), and validates specific content thresholds. It doesn't mention rate limits, error handling, or response format, leaving some gaps.

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 efficiently structured: first sentence states purpose, second adds validation specifics, third clarifies cost, fourth provides usage context, and fifth gives sibling differentiation. Every sentence adds value with zero waste.

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

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

For a single-parameter validation tool with no annotations or output schema, the description is quite complete: it covers purpose, usage context, behavioral traits (no charges), and sibling differentiation. It lacks details on output format or error cases, but is sufficient for the tool's complexity.

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

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

Schema description coverage is 100% (file_url parameter fully documented), so the baseline is 3. The description adds no additional parameter details beyond what the schema provides, but doesn't need to compensate for gaps.

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

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

The description clearly states the tool's purpose: 'Pre-check an audio file from a URL before submission' with specific validation criteria (speech content ≥10%, music-only detection). It distinguishes from siblings like barevalue_submit (for submission) and barevalue_upload (where validation is unnecessary).

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

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

Explicit guidance is provided: 'Use this for external URLs before submitting' and 'For files uploaded via barevalue_upload, validation is not needed - go directly to submit.' This clearly defines when to use this tool versus alternatives (barevalue_submit, barevalue_upload).

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

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

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool returns a webhook with a signing secret that's shown only once, implying a security-critical, non-repeatable operation. However, it lacks details on permissions, rate limits, error handling, or what happens if the URL is invalid.

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

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

The description is appropriately sized with two sentences. The first sentence states the purpose, and the second adds critical behavioral context about the signing secret. It's front-loaded with the main action, though it could be slightly more structured (e.g., explicitly listing key behaviors).

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 annotations and no output schema, the description is moderately complete. It covers the creation purpose and a key behavioral trait (one-time secret), but lacks details on return values beyond 'webhook', error conditions, or integration context. For a mutation tool with security implications, more guidance would be helpful.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters (url and events). The description adds no parameter-specific information beyond what's in the schema, such as URL format constraints or event semantics. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the verb 'create' and resource 'webhook' with the purpose 'to receive notifications'. It distinguishes from siblings like webhook_delete, webhook_update, and webhooks_list by specifying creation rather than deletion, modification, or listing. However, it doesn't explicitly differentiate from other creation tools like barevalue_submit or barevalue_upload.

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. It doesn't mention prerequisites (e.g., account setup), compare to siblings like webhook_update for modifications, or specify use cases beyond generic notifications. The agent must infer usage from the tool name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates that the action is destructive ('Delete') and irreversible ('This cannot be undone'), which are critical traits for a mutation tool. However, it doesn't mention potential side effects, error conditions, or authentication requirements.

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 two sentences: the first states the action, and the second warns of irreversibility. Every word earns its place, and the information is front-loaded, making it easy to parse quickly without unnecessary elaboration.

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 destructive tool with no annotations and no output schema, the description covers the core action and irreversibility but lacks details on permissions, response format, or error handling. Given the simplicity (one parameter, 100% schema coverage), it's minimally adequate but could be more informative about behavioral aspects.

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, with the 'webhook_id' parameter clearly documented. The description adds no additional semantic details about the parameter, such as format examples or constraints beyond what the schema provides. The baseline score of 3 reflects adequate but minimal value addition.

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 ('a webhook'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'barevalue_webhook_update' or 'barevalue_webhook_rotate_secret', but the verb 'Delete' is specific enough to convey distinct functionality.

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 like 'barevalue_webhook_update' or 'barevalue_webhook_rotate_secret'. It lacks context about prerequisites, such as needing an existing webhook ID, or exclusions, like not being usable for other resource types.

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

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

With no annotations provided, the description carries full burden and does well: it discloses the destructive effect ('old secret will immediately stop working'), security implication (secret rotation), and behavioral trait ('Returns the new secret (shown only once)'). It lacks details on permissions or rate limits, but covers key mutation aspects adequately.

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

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

The description is front-loaded with the core action, uses two efficient sentences with zero waste, and each sentence adds critical information (purpose, consequence, return behavior). It is appropriately sized for a single-parameter tool.

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 (mutation with security implications), no annotations, and no output schema, the description is mostly complete: it explains the action, destructive effect, and return value. It could improve by mentioning error cases or prerequisites, but it covers essential context well for an agent.

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

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

Schema description coverage is 100%, so the schema already documents the 'webhook_id' parameter fully. The description does not add meaning beyond what the schema provides (e.g., format or constraints), meeting the baseline of 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 the specific action ('Generate a new signing secret'), the resource ('for a webhook'), and distinguishes it from siblings like 'barevalue_webhook_create' (creation) and 'barevalue_webhook_update' (updates other than secret rotation). It uses precise verbs and scope.

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

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

The description implies usage context by stating 'The old secret will immediately stop working,' which suggests this tool should be used when needing to refresh security or invalidate old secrets. However, it does not explicitly name alternatives (e.g., when to use vs. 'barevalue_webhook_update') or provide clear exclusions, keeping it at a 4.

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

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

With no annotations provided, the description carries the full burden. It describes the tool's function (listing webhooks) and their purpose (sending notifications for order events), but does not disclose behavioral traits like pagination, rate limits, authentication needs, or output format. It adds some context but misses key operational details.

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

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

The description is two concise sentences with zero waste: the first states the tool's purpose, and the second adds valuable context about webhook functionality. It is front-loaded and efficiently structured, with every sentence earning its place.

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

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

Given no annotations, no output schema, and 0 parameters, the description is adequate for a simple list tool but could be more complete. It explains what webhooks do (order notifications), but lacks details on response format, error handling, or system constraints, leaving gaps in operational context.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description does not add parameter details, which is appropriate, but it does provide context about webhook functionality (order notifications), slightly enhancing understanding beyond the schema.

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

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

The description clearly states the verb ('List') and resource ('all configured webhooks for your account'), distinguishing it from siblings like create, delete, update, or rotate_secret webhook tools. It also adds context about webhook purpose ('send notifications when orders complete, fail, or are refunded'), which enhances understanding beyond just listing.

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

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

The description implies usage for viewing webhook configurations, but does not explicitly state when to use this tool versus alternatives (e.g., vs. webhook_update for modifying settings). It mentions webhook notifications related to orders, which provides some context, but lacks explicit guidance on 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates webhook properties, implying mutation, but doesn't cover critical aspects like required permissions, whether changes are reversible, error handling, or rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

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

The description is a single, efficient sentence that front-loads the core action ('Update an existing webhook') and specifies the updatable elements. There is no wasted text, and it directly communicates the tool's purpose without redundancy or unnecessary detail.

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 as a mutation operation with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., permissions, side effects), output values, and usage context. While the schema covers parameters well, the overall description doesn't compensate for the absence of structured data on behavior and results.

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 all parameters well-documented in the input schema (e.g., 'webhook_id' as the ID to update, 'url' as a new HTTPS URL). The description adds minimal value by listing updatable fields ('URL, events, or active status'), which aligns with the schema but doesn't provide additional syntax or format details. Baseline 3 is appropriate given 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 action ('Update') and resource ('an existing webhook'), specifying what can be updated ('URL, events, or active status'). It distinguishes from siblings like 'barevalue_webhook_create' and 'barevalue_webhook_delete' by focusing on modification rather than creation or deletion. However, it doesn't explicitly contrast with all siblings (e.g., 'barevalue_webhook_rotate_secret'), keeping it from a perfect score.

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 doesn't mention prerequisites (e.g., needing an existing webhook ID), exclusions, or comparisons to siblings like 'barevalue_webhook_create' for new webhooks or 'barevalue_webhook_delete' for removal. Usage is implied by the verb 'Update,' but explicit context is lacking.

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