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

With no annotations, the description carries full burden. It discloses that the tool sets status to approved and that the host handles confirmation, but it lacks details on idempotency, side effects (e.g., email sending is parameterized but not described), or error handling. The disclosure is minimal.

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, front-loaded with the core purpose. Highly efficient.

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

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

Given the lack of output schema and the presence of a nested parameter object, the description is adequate but incomplete. It covers purpose and a key usage guideline, but omits return values, idempotency, and potential error scenarios, which could impact agent understanding.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond the schema's descriptions, meeting the baseline but providing 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?

Clearly states 'Approve an invoice; sets status to approved.' The verb 'approve' and resource 'invoice' are specific, and it distinguishes from sibling tools like payInvoice or voidInvoice by specifying the effect on status.

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 warns that the host enforces user confirmation via an approval gate and instructs not to ask the user to re-confirm before calling. This provides clear context for when to use the tool, though it does not mention alternatives beyond the given instruction.

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 exist; the description does not disclose behavioral traits such as idempotency, side effects, authorization requirements, or the approval workflow hinted at by the __userContext parameter.

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

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

Extremely concise, one sentence front-loading the primary purpose. No unnecessary text, but could be slightly more structured.

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

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

Given the complexity (5 params, nested objects, no output schema), the description is insufficient. It omits return values, error handling, and the multi-tenant authentication context indicated by __userContext.

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 adds no additional meaning beyond what the parameter descriptions already provide. Baseline 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 verb 'attach' and resource 'payment method to a customer', but does not differentiate from similar operations like setting as default or creating a new payment method.

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 guidelines provided on when to use this tool versus alternatives (e.g., createPayment, updatePayment, deletePaymentMethod). No prerequisites or context for 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?

With no annotations, the description carries the full burden of disclosing side effects, permissions, or constraints. It only states 'Create a new accounting (GL) account', omitting details about required authorization, potential duplicates, or any immutable properties. 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?

The description is a single, front-loaded sentence with no redundancy. It efficiently conveys the core action, though it could be slightly expanded 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?

The tool has 5 parameters including a nested '__userContext' object and no output schema. The description fails to explain return behavior, error cases, or the impact of the '__userContext' fields. This leaves significant gaps for 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 schema descriptions provide 100% coverage of all 5 parameters, including valid values for 'account_category' and details for '__userContext'. The description adds no extra parameter information, but per the rule, 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 the verb 'Create' and the resource 'accounting (GL) account', making the purpose immediately understandable. However, it does not differentiate from sibling tools like 'createAggregate' or 'createContact', which also create 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 is provided on when to use this tool versus alternatives such as 'listAccounts' or 'getChartOfAccounts'. The description lacks context about prerequisites or typical workflows, making it hard for an agent to decide when to invoke this tool.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It mentions the approval gate but does not address side effects, required permissions, idempotency, rate limits, or what happens on conflict. The description is insufficient for an agent to understand the full behavioral impact.

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-loading the purpose and then a key usage note. Each sentence earns its place, and there is no extraneous text. Could be slightly more structured but overall efficient.

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

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

Given the tool has 7 parameters, nested objects, and no output schema, the description is incomplete. It does not describe the return value, error conditions, prerequisites, or the behavior of the approval gate beyond a single directive. An agent would need more context to handle this tool confidently.

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 a list of required components (name, data schema, etc.), but this largely duplicates the schema parameter descriptions. It does not explain semantics beyond what the schema provides, such as the structure of visual_query_builder or acceptable values for datasource.

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

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

The description states 'Create a new Billable Metric' which is a clear verb+resource. However, it does not distinguish from sibling tools like createRawMetric, which also creates a metric-like entity. The list of required components adds specificity but not 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?

The description provides an explicit usage guideline: 'Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.' This clarifies an important workflow step. However, it does not discuss when to use this tool versus alternatives (e.g., createRawMetric), so it lacks exclusions or when-not-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?

No annotations are provided, so the description bears full burden. It mentions creation and an approval gate, but lacks details on side effects, permissions, error states, or what happens on failure. 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 two sentences, front-loading the purpose and following with a critical usage guideline. Every word 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?

Despite 14 parameters and no output schema, the description does not address return value, error scenarios, or prerequisites beyond the approval gate. It leaves significant gaps for an AI agent to understand the full tool 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?

Schema coverage is 100%, so the schema already documents all 14 parameters. The description lists some attribute categories (name, address, etc.) but adds no semantic nuance 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 starts with 'Creates a new business entity', which is a specific verb and resource. It clearly distinguishes from sibling tools like updateBusinessEntity and listBusinessEntities. The mention of various attributes adds 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 explicitly states that the host enforces user confirmation via the approval gate and instructs not to re-confirm. This is clear usage guidance. However, it does not compare to alternative tools or specify when not to use this tool.

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

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

No annotations are provided, and the description does not disclose behavioral traits like side effects, authentication requirements, or rate limits. It only states the basic action without 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 a single sentence that efficiently conveys the tool's purpose with no unnecessary words 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?

Given the tool creates a contact with 7 parameters including a complex nested object, the description lacks details on required fields, behavior after creation, or any return value. No output schema exists to supplement this.

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%, providing clear descriptions for each parameter. The tool description adds no extra meaning beyond the schema, meeting the baseline for complete 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 'Create' and the resource 'contact', and specifies the association 'with a customer'. It is specific and distinguishes from sibling tools like updateContact and deleteContact.

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, such as when to use createCustomer or other creation tools. No when-not or context 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?

No annotations provided, so description carries full burden. It only states 'Create a new contract' without disclosing behavioral traits such as potential failure conditions, authentication requirements, or what happens on success. Lacks detail on side effects or constraints.

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

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

Three sentences with no redundancy: first sentence states purpose, second gives usage guidance, third lists included components. Well-structured 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?

Given the tool's complexity (14 parameters, nested objects, no output schema), the description lacks completeness. It does not explain return values, provide examples, or clarify how to structure phases. The schema helps, but the description should offer more contextual guidance.

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 individual parameter descriptions, so baseline is 3. The description adds minimal extra meaning beyond summarizing components like 'customer details, pricing phases, products, and billing configuration', which is already implied by 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 'Create a new contract' and resource 'in Zenskar', and distinguishes from sibling tools like createCustomer and createContractPhase by providing prerequisites. It also lists what the contract includes, making 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?

Explicitly guides agents to use this after extractContractFromRaw and createCustomer, providing a clear workflow order. However, does not mention when not to use it or alternatives for contract modifications, but for a creation tool this 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?

With no annotations provided, the description carries full burden for behavioral disclosure. It lacks information about side effects (e.g., whether the phase is appended or inserted), required permissions, reversibility, or atomicity. The only behavioral clue is the phase_type enum constraint.

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

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

The description is extremely concise: two sentences that convey the purpose, usage guidance, and a key parameter hint. No extraneous words, and the most critical 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?

Given the tool's complexity (10 parameters, nested objects, no output schema, no annotations), the description does not cover return value, preconditions (e.g., contract must exist), or the structure of the pricings array. It is adequate but leaves gaps that require inference from the 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 description coverage is 100%, so the schema already documents all parameters well. The tool description adds limited extra value (e.g., clarifying the phase_type enum, but the schema already lists the values). Thus, it meets the baseline of 3 but does not substantially enhance understanding beyond the schema.

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

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

The description clearly states the tool adds a new phase to an existing contract, and lists specific use cases (add-on expansions, mid-contract changes, distinct billing periods). This effectively differentiates it from siblings like createContractPhasePricing and createContract.

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 ('add-on expansions, mid-contract changes, or creating distinct billing periods with different pricing'), guiding the agent on when to use this tool. However, it does not mention when not to use it or compare directly with alternatives (e.g., updateContract for modifying phases).

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

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

No annotations are provided, so the description carries full burden for behavioral traits. It discloses it's a write operation ('add pricing') but does not mention side effects, error conditions, authorization requirements, or return value. The mutual exclusivity rule is more about parameter semantics than 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 two sentences, front-loaded with the action. The second sentence is somewhat long but packs essential constraints. Could be slightly more concise, but overall 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?

The description covers the core mutual exclusivity but omits context for other required parameters (contractId, phaseId) and optional parameters like start_date, end_date, etc. Given the complexity (14 params, nested objects, no output schema), it could be more complete in explaining how all pieces fit together.

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

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

The schema already has 100% description coverage for all parameters. The description adds value by clarifying the mutual exclusivity between pricing_id and pricing, and the pairing with product_id/product, which is not conveyed purely by 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 'Add pricing to a contract phase' with a specific verb and resource. It distinguishes the tool from siblings by focusing on contract phase pricing, and includes key usage constraints like 'pass EXACTLY ONE of pricing_id or pricing'.

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 that exactly one of pricing_id or pricing must be provided, and that it should be paired with product_id or product. However, it does not provide guidance on when to choose one option over the other or compare with sibling tools.

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

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

No annotations provided, so description carries full burden. Mentions versioning but does not detail update behavior (overwrite vs new version) or any side effects (destructiveness, authentication beyond schema). Adequate but not thorough.

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

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

Two concise sentences front-loaded with purpose. Parenthetical note efficiently connects to sibling tool. 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?

Adequate for a 4-param tool with no output schema. Lacks explicit behavior on duplicate prompt_name (create vs update vs version). __userContext is well-documented in schema. Minor gap for 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?

Schema coverage is 100%, so baseline 3. Description adds no extra meaning beyond schema descriptions for parameters. Does not clarify parameter usage or format.

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

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

Clearly states verb (save/create/update) and resource (reusable AI extraction prompt). Explicitly mentions sibling tool extractContractFromRaw to distinguish usage. 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?

Implies when to use (for managing extraction prompts) and mentions the consumer (extractContractFromRaw). However, lacks explicit when-not-to-use or alternatives beyond the named sibling.

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

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

No annotations are provided, so the description must fully disclose behavioral traits, but it only states the action without any details about side effects, idempotency, error handling, or implications for existing data. This is insufficient for an agent to understand the tool's behavior.

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

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

The description is a single sentence, which is concise but also very brief; it could be expanded to include key usage context without being verbose. It is minimally acceptable.

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 of 9 parameters and no output schema, the description is insufficient. It does not explain return values, error conditions, or how the tool integrates with related tools like listCustomAttributes. The description lacks 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 has 100% description coverage for all 9 parameters, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides, thus it neither improves nor detracts from parameter understanding.

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

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

The description clearly states 'Create a new custom attribute definition for an entity type,' which includes a specific verb ('create') and resource ('custom attribute definition'), distinguishing it from sibling tools that create other entities like accounts or customers.

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 usage guidelines are provided. The description does not specify when to use this tool versus alternatives, nor does it mention any prerequisites, constraints (e.g., uniqueness of attribute key), or conditions for 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?

No annotations provided; description only says 'Creates' without disclosing side effects, permissions, idempotency, rate limits, or error conditions. The internal __userContext parameter is not mentioned in the description.

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 14 words, front-loaded with the action. Efficient but could be slightly expanded for clarity 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?

Desperately incomplete for 26 parameters and no output schema. Missing return value info, error handling, authentication context, and behavioral details. The description adds almost no value beyond the schema.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no additional meaning beyond summarizing parameter categories; it does not compensate with extra context.

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

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

Description clearly states 'Creates a new customer' with a brief mention of attributes. It distinguishes from 'updateCustomer' but not from 'createCustomerAddress', which also deals with addresses.

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

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

No guidance on when to use this tool vs alternatives, no prerequisites mentioned, and no when-not-to-use advice. Given 30+ sibling tools, this is a significant gap.

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

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

No annotations provided. The description does not disclose any behavioral traits such as side effects, default behaviors (e.g., is_default fields default to false), authorization needs, or return values. With no annotations, the description bears the full burden and fails to provide necessary 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 a single, clear sentence with no unnecessary words. It is appropriately 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?

Given the complexity (12 parameters, nested objects, no output schema) and absence of annotations, the description is insufficient. It does not explain what the tool returns, any validation or constraints, or how to interpret the response. A more complete description is needed 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 description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; it merely repeats the tool's purpose. The parameter descriptions are basic but present.

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 'add', the resource 'address', and the context 'to a customer'. This distinguishes it from sibling tools like updateCustomerAddress and listCustomerAddresses.

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, no prerequisites, and no context on when not to use it. The description is purely operational.

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

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

No annotations are provided, so the description carries the burden. It discloses the approval gate behavior, which is a key trait beyond a basic create, but does not mention idempotency, error handling, or mutation specifics.

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 the second sentence provides crucial behavioral guidance. No filler 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?

Given the tool's complexity (7 parameters, nested objects), the description covers the main purpose and a key behavioral note. However, it lacks information about return values or side effects, which would be helpful for 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?

Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema (e.g., 'UUID format' is mentioned in the schema for product_id). The __userContext parameter is only hinted as 'internal'.

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 ('Creates a new entitlement') and lists specific attributes (name, description, type, units, product association), distinguishing it from update and delete siblings.

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

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

The description provides a critical usage guideline: the host enforces confirmation via the approval gate, so the agent must not ask the user to re-confirm. However, it does not compare with alternative create tools or specify when to use this tool over others.

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

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

With no annotations, the description carries full burden. It states the tool triggers payment collection but omits potential side effects (e.g., failure cases, impact on invoice status, idempotency, rate limits). Limited transparency for a payment-related 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, front-loaded with the primary action. No unnecessary words. Efficiently communicates 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 no output schema, the description should mention return values (e.g., charge ID, success status). It does not. However, it covers the basic action. For a tool with many optional parameters, some context on defaults (like connector auto-detection) is missing.

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 all parameters (100% coverage), so baseline is 3. The description adds no additional meaning beyond what the schema provides; it doesn't explain parameter relationships or usage patterns.

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 (auto-charge for invoice), and action (triggers payment collection via customer's payment method). It distinguishes from siblings like 'payInvoice' and 'generateInvoicePaymentLink' by specifying automation and use of configured payment method.

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 lacks guidance on when to use this tool versus alternatives like 'payInvoice' or 'generateInvoicePaymentLink'. No mention of prerequisites, scenarios (e.g., invoice due, customer has payment method), 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?

With no annotations, the description carries the burden. It discloses that the amount is in the invoice's currency and that the API stores amounts in cents internally. It also states the return value. However, it does not mention side effects, idempotency, 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 two sentences. The first sentence states the purpose, the second provides unit clarification and return value. No superfluous 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?

The description is brief but covers the core purpose and unit detail. Given no output schema, 'Returns the created credit note' is minimal but sufficient. However, it lacks context about prerequisites, authentication, or the structure of the returned object.

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

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

Schema coverage is 100%, but the description adds value by explaining the credit note amount unit and internal conversion ('stores amounts in cents internally'), which is not in the schema. The other parameters are adequately described in the schema.

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

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

The description clearly states it creates a credit note against a specific invoice. It specifies the verb 'create' and resource 'credit note', and the scope is against an invoice. However, it does not explicitly differentiate from sibling tools like refundPayment or voidInvoice, which could be alternatives.

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

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

The description does not provide guidance on when to use this tool over alternatives (e.g., refundPayment, voidInvoice). It lacks context about prerequisites (e.g., invoice must exist and be in a certain state) or when not to use it.

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

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

No annotations provided, so description carries full burden. It only states 'Create' but does not disclose authorization needs, validation, defaults (e.g., status_type='posted'), or side effects.

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

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

One concise sentence with no redundancy, front-loads the key action and resource.

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 complex nested parameters and accounting concepts, the description is minimal. It does not explain debit/credit semantics, output, or the role of __userContext.

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 detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool creates a new manual journal entry with debit and credit lines, which is specific and distinguishes it from sibling tools like listJournalEntries.

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, no prerequisites or when-not-to-use mentioned. The description lacks context for optimal invocation.

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

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

With no annotations, description discloses backend assigns timestamp, effect of status='success' on invoice payment, and that created status is unrealized. Could mention return value or side effects, but sufficient 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?

Single paragraph with key points front-loaded. No wasted sentences, but could be slightly more structured for easier parsing.

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

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

Covers most aspects, but lacks description of return value (no output schema) and does not address __userContext parameter. For a complex tool with 9 params, these gaps reduce 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?

Schema coverage is 100%, but description adds value beyond schema: explains type and payment_method relationship, provides example for payment_parts, clarifies amount units. Still, some parameter descriptions in schema are already clear.

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

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

Description clearly states the tool records manual/offline payments or tax-withheld amounts, equivalent to frontend Add Payment flow. Distinguishes from sibling tools like refundPayment, payInvoice, etc.

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 specifies when to use (manual/offline payments, tax withheld) and what not to use (refunds, authorizations, reversals, etc.). Provides guidance on type, status, and payment_method usage. Includes warning about status='created' not reducing amount_due.

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

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

With no annotations, the description carries full burden. It discloses that the tool hits POST /plans, creates a persistent record, and that plans start as 'draft'. It also notes the nested structure constraint. This covers key traits for a creation tool.

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

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

The description is a single paragraph, front-loaded with the main purpose, then details. It is somewhat lengthy due to nested complexity, but every sentence adds value. Could be slightly more concise, but it's 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?

Given the high complexity (nested objects, 6 parameters, no output schema), the description is fairly complete. It explains the endpoint, nested structure, phase requirements, status, and currency placement. It lacks explanation of return values, but that is partially mitigated by the schema 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?

Schema coverage is 100% (baseline 3), but the description adds significant clarity: it explains the nested structure, that currency is not top-level, the requirement for at least one phase, and provides an example for schedule. This goes well beyond the schema's 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 'Create a new plan — a reusable contract template with phased pricing', specifying the verb (create) and resource (plan). It also mentions the API endpoint and the UI page, making the tool's 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 usage guidance: the nested request body shape, currency location inside phases, the requirement to always include at least one phase, and that the plan starts as 'draft' and must be published. It does not explicitly compare with sibling tools but offers enough context for correct invocation.

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

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

No annotations are provided, so the description must carry the full burden. It merely states 'Create a new product' with no disclosure of side effects, authorization requirements, rate limits, or success/failure behavior. This is insufficient for a creation tool.

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

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

The description is a single sentence, no waste, and front-loaded with key information. However, it is overly terse and could be expanded 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 no output schema and no annotations, the description should provide more context about the tool's behavior and expected results. With 8 parameters including nested objects, the current level of detail is insufficient for the agent to use the tool correctly.

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

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

The input schema provides descriptions for all 8 parameters (100% coverage). The description adds no additional 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 clearly states the verb 'Create' and the resource 'product in the catalog', which is specific. It distinguishes from siblings like 'updateProduct' and 'createProductPricing', but could be more explicit about catalog context. Overall purpose is clear.

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

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

No usage guidelines provided. The description does not indicate when to use this tool versus alternatives, any prerequisites, or scenarios where it should not be used. This is a significant gap.

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 exist. The description reveals important behavioral details like unit_amount in major currency units and UI consequences of omission, but lacks side effects, auth requirements, or error 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 long but well-structured, front-loading the mandatory checklist. It earns its length by covering critical guidance, though minor trimming could improve 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 complexity (9 params, no output schema, nested objects), the description covers essential quirks (currency units, UI bugs) and provides a comprehensive pre-call checklist. Lacks return value details but acceptable for a create tool.

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

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

Schema coverage is 100%, baseline is 3. The description adds significant value beyond schema by providing a mandatory checklist, examples for pricing_type, and explicit warnings about required fields. This compensates for the baseline.

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

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

The description clearly states the tool creates a new pricing configuration for a product, which is a specific verb and resource. It distinguishes from siblings like createContractPhasePricing by focusing on product-level pricing, though not explicitly stated.

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 mandatory pre-call checklist and warns about UI bugs if fields are omitted. It does not explicitly compare to alternative tools but gives strong context for when to use this 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?

With no annotations, the description carries the full burden. It mentions the approval gate behavior but does not disclose other traits like whether the operation is destructive, idempotent, or requires special permissions. It implies mutation but lacks explicit safety details.

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

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

The description is extremely concise with two sentences, no redundant information, and front-loads 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?

Despite short length, the description covers the primary purpose and a critical behavioral note. Given 5 parameters, no output schema, and the complexity of creating a schema, it is adequate but could include more about return values or post-creation steps.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds no additional semantics beyond what the schema provides, meeting the baseline expectation.

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 'Usage Event schema' and defines it as the schema for ingesting usage events. It is specific about the resource and action, distinguishing it from sibling tools like createAggregate or getRawMetricById.

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

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

The description provides a clear guideline: 'Host enforces user confirmation via the approval gate; do NOT ask the user to re-confirm before calling.' This tells the agent when not to ask for confirmation, though it does not exhaustively compare to alternatives.

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

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

No annotations are provided, and the description gives no behavioral details (e.g., side effects, authentication, rate limits, or whether the tool is idempotent). The agent has no information about the implications of calling this tool.

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

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

The description is a single short sentence, which is concise but lacks sufficient detail. It is appropriately front-loaded but could benefit from additional context without being verbose.

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 and the simplicity of the tool, the description is incomplete. It fails to mention required parameters (e.g., 'name') or any constraints, leaving significant gaps for agent decision-making.

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 are already well-documented. The description adds no additional meaning beyond the schema, meeting the baseline for this dimension.

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 ('create') and the resource ('tax category'), distinguishing it from sibling tools like createAccount or createCustomer. However, it lacks specificity about the context or constraints.

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., updating vs. creating). No prerequisites or conditions are mentioned, leaving the agent with minimal context for decision-making.

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 that the action is destructive and irreversible ('Permanently delete', 'cannot be undone') and explains the host's approval gate. However, it does not mention potential side effects on related entities (e.g., invoices using the metric) or the return 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 three sentences, efficient and front-loaded. Each sentence adds value: purpose, destructiveness warning, and usage guideline. No extraneous 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 delete tool with no output schema and no annotations, the description provides essential information: what it does, when to call, and behavioral notes. It lacks details on error handling or edge cases, but is generally complete.

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

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

Schema coverage is 100%, and the description does not add meaningful parameter information beyond what the schema already provides. The aggregateId is described as UUID in the schema, and __userContext is internal. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Permanently delete a Billable Metric.' It uses a specific verb ('delete') and resource ('Billable Metric'), and distinguishes from sibling delete tools by specifying 'THIS billable metric'. The purpose is 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?

Explicitly states when to use: 'ONLY call when the user explicitly says 'delete' or 'remove' for THIS billable metric.' Also instructs not to ask the user to re-confirm because the host enforces approval. This provides clear guidance on tool invocation.

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 labels the tool as 'DESTRUCTIVE' and notes that the host enforces user confirmation via an approval gate. This adds behavioral context beyond the input schema, though it could mention potential side effects like cascading deletions.

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

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

The description is three sentences, each with a distinct purpose: stating the action, providing usage guidelines, and noting behavioral context. It is front-loaded and contains 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?

The tool is simple (delete a contact). The description covers the destructive nature, usage conditions, and the host's approval mechanism. It does not specify return values, but given no output schema, this is 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?

Schema description coverage is 100%, so the input schema already documents both parameters adequately. The description does not add additional meaning beyond the schema, earning a baseline score of 3.

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

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

The description clearly states 'Permanently delete a contact by ID', specifying the verb (delete), resource (contact), and method (by ID). This distinguishes it from sibling tools like deleteCustomer or deleteContract.

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 'only call when the user explicitly says delete for THIS contact; never as automatic recovery from another failed operation'. It also instructs not to ask the user for re-confirmation because the host enforces it. These conditions are clear and guide correct 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?

No annotations are provided, so the description carries full burden. It discloses that the action is 'DESTRUCTIVE' and 'removes all phases, products, and pricing associations'. It also mentions that the host enforces user confirmation via an approval gate, clarifying the identity verification process without requiring the agent to ask the user again.

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 with the primary purpose. Every sentence earns its place: first states purpose, then constraints, then destructive behavior, then usage rules, then error handling, and finally confirmation protocol. No redundant or unclear statements.

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 that there is no output schema, the description covers the essential aspects for agent invocation: what the tool does, when to use it, side effects, and error handling. However, it does not specify what the tool returns upon success (e.g., confirmation message or deleted object), leaving a minor gap in 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 input schema has 100% coverage for contractId and __userContext. The description adds meaning beyond the schema by stating the precondition that the contract must have status='draft', which is a critical constraint not found in the schema. However, it does not elaborate further on the parameters themselves.

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 DRAFT contract' and specifies that it only works on contracts with status='draft'. This explicitly defines the action (delete) and the exact resource (draft contracts), distinguishing it from other delete tools like deleteContact or deleteCustomer, and from other contract operations like pauseContract or expireContract.

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 extensive usage guidance: 'Do NOT call on ACTIVE, EXPIRED, or PAUSED contracts', 'NEVER call as automatic recovery from another failed operation', and 'ONLY call when the user explicitly says delete or remove for THIS draft contract'. It also instructs to surface error verbatim for non-destructive failures and notes that the host handles confirmation, so no re-confirmation is needed.

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

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

With no annotations, the description carries full behavioral burden. It clearly labels the operation as DESTRUCTIVE and irreversible, and adds important context about preconditions and host-enforced confirmation. Missing details on return/errors but sufficient for a destructive action.

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: action nature, preconditions, usage rule. No redundant or irrelevant 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 destructive tool with no output schema, the description provides necessary context: preconditions, usage rules, behavioral nature. Minor omission of success/error response but overall adequate.

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

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

Schema description coverage is 100%, with clear UUID description for customerId and internal context for __userContext. The description adds no additional semantic value beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action (permanently delete), resource (customer by ID), and explicitly notes it is destructive and irreversible, distinguishing it from update or create siblings.

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

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

Explicitly states when to call: only on explicit user 'delete' for this customer, not automatic recovery. Provides preconditions (no active contracts/invoices) and instructs not to ask for re-confirmation due to host approval gate.

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?

Despite no annotations, the description warns 'DESTRUCTIVE: cannot be undone' and explains the approval process. It adds context about irreversible effects but could mention potential side effects or required permissions.

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

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

The description is concise with three sentences, each serving a purpose: stating the action, emphasizing destructiveness, and providing usage instructions. No fluff.

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

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

For a deletion tool with one required parameter, the description covers purpose, destructiveness, and confirmation flow. It lacks return value information but is otherwise sufficient.

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

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

Schema coverage is 100% with clear descriptions for entitlementId and __userContext. The description does not add parameter meaning beyond the schema, 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 explicitly states 'Permanently delete an entitlement.' It clearly identifies the verb (delete) and the resource (entitlement), distinguishing it from sibling tools like createEntitlement or updateEntitlement.

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 specific guidance: 'ONLY call when the user explicitly says delete or remove for THIS entitlement.' It also clarifies that the host enforces confirmation via an approval gate and instructs the agent not to ask for re-confirmation, reducing ambiguity.

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

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

Despite no annotations, the description fully discloses destructive nature, permanent removal, and the host-enforced confirmation via approval gate (so agent shouldn't ask again). This meets the burden for behavioral 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?

Highly concise: three clearly structured sentences covering constraint, destructive warning, and procedural caution. No wasted words, all earned their 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 destructive delete tool, this description covers preconditions, status restriction, alternatives, and agent behavior guidance. Complete despite lack of 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%, so baseline 3 applies. Description doesn't add extra details about invoiceId format or __userContext beyond schema, but it doesn't need to.

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 permanently deletes only draft invoices, with explicit verb 'delete' and resource 'draft invoice'. It also distinguishes from siblings like voidInvoice and createInvoiceCreditNote.

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

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

Provides explicit when to use (only on user explicit 'delete' for this invoice, draft status) and when not (approved invoices, automatic recovery). Names alternative tools for 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?

Discloses destructive nature, permanent deletion, eligibility status requirement, and interaction with approval gate. Lacks details on error handling or return 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?

Three concise, front-loaded sentences with no wasted words. Key points are immediately clear.

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

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

Covers purpose, usage constraints, and behavioral expectations well given no output schema. Could mention what happens if payment status not eligible.

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 parameters. Description adds no extra parameter semantics beyond what 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?

Clearly states it deletes a manual payment record with specific verb and resource, distinguishing it from siblings like editManualPayment or deleteInvoice.

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 call (user says 'delete') and when not (automatic recovery), and clarifies host enforcement of confirmation, eliminating need for re-confirmation.

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 fully carries the burden of disclosing behavioral traits. It labels the tool as 'DESTRUCTIVE' and details specific consequences: saved details removed and auto-charges will fail. It also explains the host's confirmation enforcement via the approval gate, covering both safety and workflow 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 exceptionally concise, consisting of two sentences that each add critical value. The first sentence states the primary action and its destructive nature, while the second provides usage guidelines and behavioral context. No unnecessary words 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?

Given the tool's simplicity (a delete operation), the description is complete. It explains the outcome, consequences, and the host's approval workflow. There is no output schema, but the description sufficiently covers what the agent needs to know to invoke the tool correctly.

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

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

The input schema has 100% description coverage, providing full details for the two required parameters (customerId, paymentMethodId). The description does not add new parameter information beyond what the schema already provides, so it meets the baseline for high schema coverage without exceeding it.

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

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

The description clearly states the tool's action: 'Permanently delete a payment method from a customer.' It specifies the resource (payment method) and the consequence (removal of card/bank details, causing recurring charges to fail). This distinguishes it from sibling tools like attachPaymentMethod or listPaymentMethods.

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 when-to-use guidance: 'Only call when the user explicitly says delete for THIS payment method.' It also instructs the agent not to ask for re-confirmation because the host already enforces confirmation via the approval gate. This clearly communicates usage constraints and behavior.

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, and the description does not disclose any behavioral traits beyond the basic action. Information on authentication, rate limits, side effects (if any) is missing.

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 redundancy. It is front-loaded but lacks depth.

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 existence of siblings like getInvoiceById, the description does not clarify the difference. No output schema, and no information on return format or pagination.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds no additional meaning beyond what the schema already provides, meeting the baseline.

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

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

The description clearly states 'Download an invoice in JSON format', identifying the verb, resource, and format. However, it does not distinguish from similar tools like getInvoiceById which may also return JSON.

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

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

No guidance on when to use this tool versus alternatives like getInvoiceById or getInvoiceSummary. No context on prerequisites or limitations.

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

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

With no annotations provided, the description carries full burden. It mentions using a specific endpoint but discloses no behavioral traits such as authorization requirements, destructiveness, or side effects. The edit operation implies mutation, but no details on reversibility or impact are given.

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

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

The description is a single, concise sentence with no redundancy. However, it could benefit from more structure to improve readability and scannability.

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 7 parameters, nested objects, no output schema, and no annotations, the description is insufficient. It fails to explain return values, required permissions, or post-edit effects, leaving significant gaps for agent understanding.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value by listing example fields (amount, method) but does not clarify complex parameters like payment_method_details or payment_parts. Schema descriptions already cover 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 it edits a manual payment's details, specifying the verb (edit), resource (manual payment), and scope (details like amount, method). The name reinforces this, distinguishing it from sibling tools like 'updatePayment' which likely handles other payment 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?

No guidance on when to use this tool versus alternatives such as 'updatePayment' or 'deleteManualPayment'. The description does not specify context or exclusions, leaving the agent to infer based on the 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?

No annotations provided, so the description carries full burden. It identifies the action (edit) and lists editable fields, but omits side effects, permissions, idempotency, or whether the operation is destructive. Basic but not comprehensive.

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

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

Two sentences: the first states the purpose, the second gives usage guidance. No wasted words. Front-loaded with the core action.

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

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

For a moderate tool with 6 parameters and no output schema, the description covers core usage well. However, it lacks return value information (e.g., what the response contains) and doesn't mention the internal __userContext parameter, leaving a small gap.

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

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

Schema coverage is 100%, baseline 3. The description adds context by tying parameters to user scenarios (e.g., 'end_date' as 'resume date', 'pause_phase_id' for disambiguation). This enhances 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 explicitly states 'Edit an existing pause phase on a contract' with a specific verb and resource. It distinguishes from siblings like 'pauseContract' and 'resumeContract' by referencing error-driven scenarios.

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 when-to-use scenarios: 'when resumeContract returns pause phase not found' and enumerates user intents (set resume date, shift start, change policy). Mentions the underlying endpoint (PATCH) for reference.

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?

Discloses idempotency is NO, timing (end of day 23:59:59.999999), and host-enforced user confirmation via approval gate. Specifies error behavior for already-expired contracts. No annotations provided, so description fully covers behavioral traits.

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

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

Description is efficiently structured with front-loaded purpose and clear rules. Slightly verbose with 'Idempotency: NO' phrasing, but overall no wasted sentences.

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

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

No output schema, but description adequately covers all critical context: allowed states, error handling, timing, confirmation flow. Lacks response format, but mutation tools often omit this. Sufficient for agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: expiry_date defaults to today and must not be earlier than start_date, and contractId is a UUID. Adds value beyond schema.

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

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

Clearly states the tool expires an ACTIVE or PAUSED contract by adjusting its end_date, specifying allowed status transitions (ACTIVE→EXPIRED, PAUSED→EXPIRED). Unambiguously distinguishes from destructive tools like deleteContract.

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 (contracts with status ACTIVE or PAUSED), when not to use (already-expired returns 400), and provides alternatives (verify via getContractById, do not escalate to deleteContract). Also instructs not to ask user for confirmation due to approval gate.

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 is the sole source of behavioral information. It mentions AI analysis and extraction of specific fields but does not disclose side effects (e.g., whether data is stored), authentication requirements, error handling, or rate limits. It adequately describes the tool's function but lacks depth.

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

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

The description is concise, consisting of two sentences that effectively convey the tool's purpose and usage context without 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 absence of an output schema and annotations, the description should provide more information about the return format or behavior. It mentions extracted fields but does not specify the structure of the output, leaving agents unclear about what to expect.

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 the param descriptions in the schema are already detailed (e.g., content includes an example). The tool description adds contextual value by explaining the purpose of the extracted data but does not significantly enhance understanding of individual parameters 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 ('Extract'), resource ('contract data'), and method ('from raw text content using AI'). It distinguishes the tool from siblings like createContract by indicating that it processes unstructured text to produce structured data for subsequent use.

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

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

The description explains when to use the tool (when raw text describes a contract) and suggests next steps using createCustomer and createContract tools. It does not explicitly state when not to use it or mention alternatives, but the context is clear.

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

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

With no annotations, the description fully discloses the tool's behavior: it handles all products in the window as line items, requires exact date matching, and explains consequences of missing or incorrect parameters. No contradictions.

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

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

The description is well-structured: purpose first, then granularity, mandatory pre-step, parameter details, and failure modes. Each sentence adds value; no fluff. Front-loaded 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?

Despite lacking an output schema, the description covers expected return values (invoice_ids, $0 invoice) and edge cases. With 7 parameters and complex date handling, the description provides comprehensive guidance for 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?

Schema coverage is 100%, but the description adds critical context beyond schema: explains why bill_for_date must match exactly, consequences of omitting billing_cycle_start_day, and date format preferences. This significantly enhances usability.

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 generates an invoice for a single contract+customer over a billing window, with granularity per phase, not per product. It distinguishes from related tools like createInvoiceCharge by explaining its 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?

Explicitly mandates calling getContractBillingCycles as a pre-step, provides detailed instructions on how to copy date fields, and lists known failure modes with actionable fixes. This guides correct usage and avoids common mistakes.

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

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

No annotations provided, so description carries full burden. Only states what it does, not how it behaves (e.g., whether it creates resources, requires authentication, or has side effects).

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 is concise, but it lacks structure and could benefit from additional context to justify its conciseness given the parameter complexity.

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

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

With no output schema, no annotations, and a complex __userContext parameter, the description is incomplete. It does not explain return values, authentication requirements, or side effects.

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

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

Schema coverage is 100%, but description adds only the 'custom amount' constraint ('must be less than the amount due'). The complex __userContext parameter is not explained. Baseline is 3.

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

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

The description clearly states the action ('Generate') and the resource ('payment link') with context ('for a specific invoice'), making it distinct from sibling tools that involve invoices but not payment link generation.

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

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

No guidance on when to use this tool over alternatives like payInvoice or generateInvoice. No mention of prerequisites or conditions for 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?

No annotations provided, so description bears full burden. It does not disclose read-only nature, authentication needs, performance implications, or what balance includes (e.g., pending transactions).

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: first conveys purpose, second lists filtering capabilities. No fluff, 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?

No output schema, so description should explain return format but does not. Missing side effects, return value structure, or prerequisites. Moderate complexity with 8 params, yet incomplete.

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. Description adds some value by summarizing filters, but does not add new syntax or format details beyond 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 'Retrieve' and resource 'account balance', with specific filtering options. It distinguishes from sibling tools like listAccounts 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?

No explicit guidance on when to use this tool vs alternatives like getBalanceSheet or getIncomeStatement. Missing 'when not to use' or specific context.

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

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

No annotations provided, yet description lacks disclosure of side effects, authentication needs, rate limits, or return format; minimal behavioral 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?

Single sentence is concise and front-loaded, but could include additional context without being verbose.

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

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

No output schema and no annotations; description fails to explain return values, error conditions, or relationship to other tools, making it incomplete for a detail retrieval tool.

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

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

Schema coverage is 100% with descriptions for both parameters; description does not add meaning beyond schema, so baseline score 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?

Description clearly states verb 'Get' and resource 'details of a Billable Metric by its ID', distinguishing it from siblings like getAggregateEstimates, getAggregateLogs, etc.

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

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

No guidance on when to use this tool vs alternatives such as getAggregateEstimates or getAggregateLogs, and no prerequisites or exclusions mentioned.

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

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

No annotations are provided, and the description does not disclose behavioral traits such as side effects, authentication needs, or data freshness. For a tool that returns estimates, lack of transparency about computation or constraints is a notable 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?

The description is concise and direct, using a single sentence. While it may be too brief, it effectively communicates the core action without 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?

The description lacks completeness given the complexity: no output schema, no annotations, and a nested __userContext parameter. It does not explain return format, constraints, or the nature of estimates.

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

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

Schema description coverage is 100%, with each parameter well-documented. The description itself adds no additional parameter meaning, so it meets 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 the tool retrieves Billable Metric estimates, specifying both the verb and resource. While it does not explicitly distinguish from siblings like getAggregateById, the resource name implies a different purpose, so it is reasonably distinct.

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, nor any context or preconditions. It simply states the action without any 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not mention authentication needs, rate limits, side effects, or the nature of the operation (read-only). Only minimal purpose is conveyed.

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 19-word sentence that is concise and front-loaded with the main action. It is efficient but could be more structured without harming 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?

With 7 parameters and no output schema, the description lacks detail on return format, pagination, or behavior of the 'month' parameter vs. date range. It is incomplete for a tool with this complexity.

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

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

Schema coverage is 100%, with each parameter described in the schema. The description adds a summary of optional filters but does not provide additional meaning beyond what the schema already offers. 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', the resource 'logs related to a Billable Metric (aggregate)', and the identifier 'by ID', with optional date and customer filters. It distinguishes from siblings like getAggregateById and getRawMetricLogs.

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 fetching logs of a specific aggregate with optional filters, but it does not provide explicit guidance on when to use this tool versus alternatives like getRawMetricLogs, nor does it mention when not to use it.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It mentions 'debugging' and 'schema inspection' but does not state whether the tool is read-only, destructive, or requires any specific permissions. Missing critical behavioral traits 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?

Two sentences with no waste. The purpose is front-loaded, followed by usage context. 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?

Given the tool has only one generic parameter and no output schema, the description adequately covers purpose and usage context. However, behavioral transparency is missing, leaving a gap for a non-annotated tool.

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

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

Schema coverage is 100% due to the `__userContext` parameter being documented, but the parameter is a generic context object with no tool-specific meaning. The description adds no value beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states that the tool 'Show the underlying storage/schema definitions for Billable Metrics', using specific verb+resource. It distinguishes itself from sibling tools like `getAggregateById` by focusing on schema definitions, not aggregate data.

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 tool is described as 'mainly useful for advanced debugging, SQL/schema inspection, and integration work rather than day-to-day business operations'. This provides clear context on when to use it (advanced scenarios) and when not to (day-to-day). No explicit alternatives are given, but the guidance 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?

No annotations are provided, so the description must fully convey behavioral traits. However, it only states the basic function. It does not disclose whether the tool requires authentication (implied by the __userContext parameter but not stated), rate limits, or the nature of 'available tags' (e.g., user-specific, org-wide). No output format is mentioned.

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 communicates the core purpose without waste. It is appropriately front-loaded. However, for a tool with a parameter that requires explanation, slightly more detail could be warranted without sacrificing 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 absence of an output schema and annotations, the description should explain what the tool returns and any side effects. It fails to mention the return format, pagination, or whether results are filtered by context. The description is incomplete for safe and 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 has 100% coverage via the description of __userContext. The tool description adds no extra meaning beyond the schema. Baseline is 3, and the description does not improve or degrade it.

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 available tags for invoices' clearly states the action (Get) and the resource (all available tags for invoices). The tool name and description uniquely identify it among siblings, which include many invoice-related tools but none specifically for tags.

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. There is no mention of prerequisites, context, or scenarios where other tools like listInvoices might be more appropriate. The description lacks any 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?

No annotations provided, so description carries full burden. It does not disclose behavioral traits such as read-only nature, authentication needs, rate limits, pagination details, or output format. Basic retrieval action stated without behavioral 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?

Single sentence, front-loaded with main purpose, no unnecessary words. Efficient and to the point.

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 (12 parameters, no output schema, nested objects), description covers high-level purpose and filter capabilities but lacks details on return format, pagination, and behavioral aspects. Adequate but notable 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%, providing baseline of 3. Description adds meaning by explaining scoping capabilities (per-customer, per-contract, per-account) and selection of currency/cadence, going beyond schema descriptions. Not exhaustive but adds 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?

Description clearly states it retrieves the balance sheet report and identifies key elements (assets, liabilities, equity). It mentions scoping filters, currency, and cadence selection, but does not distinguish from sibling tools like getIncomeStatement. Purpose is specific but lacks 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?

Description implies when to use scoping filters and selection options, but does not guide when to use this tool over alternatives (e.g., getIncomeStatement). No explicit context or exclusions provided.

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

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

No annotations provided, so description must carry full burden. It only says 'Retrieve', implying safe read, but does not disclose error behavior, authentication needs, rate limits, or what happens if entity not found. Minimal 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?

Single sentence, front-loaded, no extraneous information. Efficient and clear.

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

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

No output schema and no behavioral context about return values. For a tool with a nested parameter and no annotations, description should provide more completeness, such as response structure or usage with userContext.

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. Description adds no extra meaning beyond what schema already provides for entityId and __userContext.

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

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

Description clearly states verb (retrieve), resource (business entity), and method (by ID). It distinguishes from siblings like listBusinessEntities or other getById 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?

No guidance on when to use this tool versus alternatives like listBusinessEntities or other getById tools. Missing context 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?

The description discloses the read-only nature and the type of data returned (account categories and hierarchy). However, it does not mention authentication requirements, rate limits, or any side effects. Since no annotations are provided, the description carries full burden but covers only basic behavioral traits.

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 (17 words) that front-loads the action and resource. Every word is necessary and contributes to understanding. No 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?

The description covers the core functionality but lacks detail on output format or structure. Since no output schema exists, the description should ideally clarify the form of the hierarchical structure (e.g., nested JSON or flat list). It is adequate for a simple read tool but not exhaustive.

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% (the only parameter __userContext is fully described in the schema). The description adds no additional parameter information beyond what the schema provides. Per guidelines, baseline is 3 when coverage is high.

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 clearly identifies the resource as 'the chart of accounts for the organization'. It further specifies the output as 'listing all account categories and their hierarchical structure', which differentiates it from sibling tools like getAccountBalance or getBalanceSheet. The purpose is unambiguous and distinct.

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