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

The annotations (openWorldHint and idempotentHint) indicate side effects and idempotency, but the description adds no extra behavioral context. It merely restates the title without disclosing consequences such as the link becoming hidden or the operation's reversibility.

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 directly and clearly conveys the tool's function. It is appropriately brief, with no wasted words, and the key action 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?

The description is minimally adequate for a simple two-parameter toggle. The schema and annotations cover parameter details and idempotency, but the description lacks information about return values, error conditions, or the operational impact of archiving (e.g., whether the link disappears from lists), leaving some gaps in context.

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

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

The input schema already provides complete descriptions for both parameters (100% coverage), so the description does not need to add parameter details. The phrase 'archive or unarchive' aligns with the archived boolean, but adds no meaning beyond what the schema already states.

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

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

The description explicitly states the action with a specific verb ('archive or unarchive') and a clear resource ('Payment Link'), making the tool's purpose immediately obvious. It also distinguishes itself from sibling tools like get_link and create_link, as no other sibling handles archiving.

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 when-to-use or when-not-to-use guidance, nor does it mention alternatives or prerequisites. Usage is only implied by the tool's name and the archived parameter, but the description itself offers no explicit context for choosing 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?

Annotations include destructiveHint=true and openWorldHint=true, but the description only adds 'returns a checkout URL.' It does not explain side effects, what the destructive hint means, or any operational caveats.

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, and contains zero filler. It conveys purpose and primary return value efficiently.

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 basic invocation given full schema coverage, but lacks usage guidance and behavioral context for a side-effecting tool with no output schema. The destructiveHint annotation remains unaddressed.

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

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

Input schema has 100% description coverage, so all parameters are already documented. The description adds no parameter-specific detail, which is acceptable given the schema.

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

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

Description uses specific verb 'Create' with resource 'hosted checkout session' and notes the return value ('returns a checkout URL'). This clearly distinguishes the tool from sibling creation tools like create_payment_intent.

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 given on when to use this tool vs alternatives such as create_payment_intent or create_source. There are no exclusions or explicit context clues beyond the word 'hosted'.

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

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

The description adds specific behavioral context beyond the openWorldHint annotation by explicitly stating it stores PII and exists for reuse across payments. This clarifies the persistence side effect, though it could mention data retention, security, or idempotency, but with the annotation covering general side effects, the added detail is valuable.

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

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

The description is a single, concise sentence that front-loads the action and purpose. It contains no filler or redundant information.

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

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

The description and schema together cover the tool's inputs and basic purpose, but with no output schema, the description does not mention what the tool returns (e.g., customer ID or object). It also lacks guidance on edge cases or prerequisites, making it minimally 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%, so the parameters are already well-documented in the schema. The description adds no additional parameter-specific meaning, aligning with the baseline of 3.

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

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

The description clearly states a specific action (create) and resource (customer record), and adds purpose ('stores PII for reuse across payments'). This distinguishes it from sibling tools like create_payment or create_payment_method, which create other entities.

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

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

The description implies when to use this tool through 'stores PII for reuse across payments,' suggesting it's for storing customer data for future transactions. However, it does not explicitly state when not to use it or mention alternatives, such as create_payment_method for non-PII payment details.

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

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

Annotations include openWorldHint: true and destructiveHint: true, but the description adds no clarification about what these side effects actually are (e.g., whether the link expires, if it is irreversibly created, or what destructive means in this context). The description only mentions return values, not the behavioral implications of creating a link. Since annotations are broad and unhelpful, the description carries more burden than it fulfills.

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

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

The description is two short sentences that are front-loaded with the core purpose and key return values. No filler or repetition of schema details. Every sentence contributes meaningful 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 straightforward creation tool with 4 parameters fully documented in the schema, the description is sufficient: it states what it does, the return values, and the no-code context. However, it does not address the unusual destructiveHint annotation or any side effects, which would be useful but not critical for invoking the tool. Overall, it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100%, with all four parameters already having clear descriptions (e.g., amount in centavos, remarks as internal note). The description adds no additional parameter-level information, so the baseline of 3 applies because the schema does the heavy lifting.

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

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

The description clearly states 'Create a PayMongo Payment Link' with a specific verb and resource, and adds the differentiator 'no-code shareable checkout' to distinguish it from similar sibling tools like create_checkout. It also mentions expected return values (checkout_url and reference_number), making the purpose unambiguous.

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

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

The phrase 'no-code shareable checkout' implies when to use this tool (when you want a hosted payment page without building UI), but there is no explicit guidance on when not to use it or how it differs from siblings like create_checkout or create_payment_intent. No exclusions or alternatives are named, so it remains at an implied-usage level.

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

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

The annotations already flag destructiveHint and openWorldHint. The description adds 'moves money', which explicitly discloses the financial consequence and clarifies the nature of the destructive action. However, it does not disclose additional behaviors such as idempotency, failure modes, or return value structure.

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 that delivers the core action and consequence without any filler. All words contribute meaning, making it ideal.

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

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

The description is minimal, but combined with the detailed schema (100% coverage) and annotations (destructive, open world), it provides enough for an agent to understand the basic operation. However, it lacks guidance on use cases and alternatives, and does not describe the return value or potential side effects beyond 'moves money', which keeps it from being fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'chargeable source' which aligns with the source_id parameter, but it does not provide any additional parameter semantics beyond what the schema already documents (e.g., amount in centavos, currency default).

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

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

The description uses a specific verb 'charge' and identifies the resource as 'a chargeable source', clearly indicating this tool performs a direct charge to create a payment. This distinguishes it from sibling tools like create_payment_intent, which creates an intent rather than an immediate charge.

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 explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. The phrase 'to create a payment' implies it is for immediate payment creation, but there is no explicit guidance for choosing this over create_payment_intent or other siblings.

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

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

Annotations already flag the tool as having external side effects (openWorldHint, destructiveHint). The description adds that the intent tracks the payment lifecycle, but does not disclose details like the two-step confirm flow or that the returned intent must be used later.

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

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

A single, front-loaded sentence with zero wasted words. It immediately states the action and object, making it easy to scan.

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 adequate for a basic understanding but incomplete for a payment tool with no output schema. It could mention that the returned intent must be confirmed or how it differs from a checkout session, leaving the agent to infer the next 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 descriptions cover 100% of parameters with rich details (e.g., amount in centavos, minimum, allowed methods), so the tool description adds no additional parameter meaning beyond what the schema already provides.

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

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

The description clearly identifies the action ('Create'), the resource ('a PayMongo payment intent'), and its purpose ('tracks a payment through its lifecycle'), distinguishing it from sibling tools like create_checkout or create_source.

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

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

The description implies the use case (creating a payment intent) but gives no explicit guidance on when to choose this over alternatives such as create_checkout or create_payment, nor any exclusions or prerequisites.

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

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

The description adds a meaningful warning to 'handle card data with care', indicative of sensitive data handling. However, it does not disclose side effects beyond creation (e.g., whether it validates, charges, or stores the card). The openWorldHint annotation is not explained, so the description provides only modest 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?

The description is two concise sentences, front-loading the core purpose and including only a brief necessary caution. No wasted words or redundant schema 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?

For a tool with 3 parameters, nested objects, and no output schema, the description is minimal but adequate for basic invocation. It explains the role in the payment workflow ('attach to a payment intent') and warns about sensitive data, but lacks information on return values, error behavior, or how the payment method is ultimately attached.

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

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

The input schema already provides descriptions for all parameters (100% coverage), so the description does not need to repeat them. The description mentions 'card' as an example, which aligns with the schema's 'details' field, but adds no additional parameter-level semantics.

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 a payment method') and provides an example ('e.g. a card') with a purpose ('to attach to a payment intent'). This distinguishes it from general creation tools, though it does not explicitly contrast with sibling tools like create_source, leaving some ambiguity.

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

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

The phrase 'to attach to a payment intent' gives clear context for when this tool should be used, implying the intended workflow. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true. The description adds the behavioral detail that money moves back to the customer, including full or partial refunds. However, it does not disclose other traits like idempotency or reversibility, which is a minor 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 a single, front-loaded sentence that conveys the core purpose and key attribute (partial/full) without unnecessary words. It is concise and well-structured.

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

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

For a simple refund creation tool, the description captures the core behavior but omits edge-case constraints such as payment state requirements or maximum refund limits. The annotations and schema provide safety and parameter details, making the description minimally 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?

All three parameters have descriptions in the schema, achieving 100% schema coverage. The tool description itself adds no parameter-specific details, so it relies on the schema, which is sufficient.

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

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

The description uses the specific verb 'Refund' with the resource 'a payment', and clarifies the scope with 'fully or partially'. This clearly distinguishes it from sibling read tools like get_refund and list_refunds.

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 refunding payments but does not explicitly state when to use it versus alternatives or exclude cases. The parenthetical provides context about the effect but lacks explicit guidance on when not to use the tool.

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

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

With annotations already indicating destructive behavior (destructiveHint=true) and external world interaction (openWorldHint=true), the description adds the key behavioral detail that the tool 'returns a redirect checkout URL', which is especially valuable because there is no output schema. It also clarifies the specific e-wallet types. This goes beyond the annotations and helps the agent anticipate the result.

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. It states the core action first and adds the return behavior in parentheses. No wasted words 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?

For a tool with 5 parameters and no output schema, the description covers the essential context: purpose, specific payment types, and the return value (redirect checkout URL). The schema already documents parameters fully, so the description is sufficient for basic selection and invocation. It could mention prerequisites or side effects, but the annotation hints and return description cover most needs.

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

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

The input schema provides 100% description coverage for all parameters, including amount units and type enum values. The description adds minimal extra parameter meaning—only naming the e-wallet types (GCash/GrabPay) already present in the schema. It does not exceed the baseline set by the rich 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 specific verb and resource: 'Create a GCash/GrabPay payment source'. It also differentiates from sibling tools like create_payment_intent or create_checkout by naming the specific payment source type and the return value (a redirect checkout URL). This leaves no ambiguity about what the tool does.

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

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

The description implies the usage context: you need a GCash/GrabPay payment source with a redirect checkout URL. However, it does not explicitly state when to use this tool over alternatives such as create_payment_intent or create_checkout, nor does it provide exclusion criteria. This is implied usage rather than explicit guidance.

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

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

The description discloses a key behavioral trait beyond the annotation: the response includes a per-webhook signing secret that should be stored for signature verification. This adds practical context that the schema and the vague openWorldHint annotation do not cover. It does not contradict any annotations, and the annotation (openWorldHint) is weak, so the description carries more weight here.

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 consists of two concise sentences. The first sentence states the core purpose, and the second provides a critical operational detail. No filler or redundant content. It is well-front-loaded and 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 low complexity (2 params, no nested objects, no output schema), the description covers the essential return-value information (signing secret) and the purpose. It does not explain post-creation behavior (e.g., whether the webhook is active immediately) or prerequisites, but these are not critical given the simple scope and presence of sibling tools for other operations. Overall, it is complete enough for an agent to invoke correctly.

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

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

Schema coverage is 100%, with both parameters (url and events) having detailed descriptions. The tool description adds no parameter-specific information, but the baseline is 3 because the schema already provides the necessary semantics. No additional value is provided beyond the schema, but none is needed.

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

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

The description clearly states the specific action ('Register a webhook endpoint') and its purpose ('for event delivery'). This distinguishes it from sibling tools like list_webhooks, get_webhook, and update_webhook, which perform different operations on webhook 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?

The usage is implied by the verb 'register' and the resource type, but no explicit guidance is given about when to use this tool versus alternatives. It doesn't mention exclusions or prerequisites, and doesn't reference the sibling tools. For a straightforward create operation in a well-understood context, implied usage is acceptable but not exemplary.

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

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

The description adds no behavioral context beyond what the annotations already provide. It simply restates the purpose and the lookup method, which is already evident from the schema. There is no mention of error handling, response details, rate limits, or other 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, clear sentence with no filler or redundant phrasing. It is appropriately front-loaded and every word contributes to conveying 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?

For a simple get-by-ID tool with one well-documented parameter and strong annotations, the description is sufficient. The operation is straightforward, and although it lacks usage context, the simplicity of the tool reduces the need for additional detail.

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

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

Schema coverage is 100%, so the schema already documents the sole parameter with a clear format hint ('cs_...'). The description's 'by its ID' adds no further semantic value, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Retrieve' and clearly identifies the resource as a 'checkout session' with lookup by ID. This distinguishes it from sibling tools like get_payment_intent or get_source, making the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_payment_intent or list_payments. It lacks any contextual cues about when this is the appropriate choice or what conditions warrant its use.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true, covering the safety profile. The description adds no behavioral details beyond the literal action, such as return format, error behavior, or any side effects. It does not contradict annotations.

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

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

The description is a single sentence, front-loaded with the primary action, and contains zero filler or redundant text. It is optimally concise for the tool's simplicity.

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 (one parameter, no output schema), and annotations provide strong safety context. The description is sufficient for basic usage, though it omits details like response contents or error handling, which would make it more complete.

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

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

Schema coverage is 100%, with customer_id documented as 'Customer ID (cus_...).' The description's 'by its ID' adds no new meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Retrieve' with a clear resource 'customer' and method 'by its ID'. This clearly distinguishes it from sibling tools like list_customers (plural, listing) and create_customer (creating).

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

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

The description implies usage when you have a customer ID, but provides no explicit guidance on when to use this tool versus alternatives like list_customers or get_checkout. No exclusions or alternative tool references are given.

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

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

The description adds the behavioral nuance that either link_id or reference_number can be used for lookup, which is not in the annotations. Since readOnlyHint and idempotentHint already disclose the safety profile, the description's contribution is modest. It does not mention behavior when both or neither parameters are provided.

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

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

The description is a single, front-loaded sentence that conveys the essential purpose and lookup methods without any redundant text. Every phrase earns its place.

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

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

For a simple read-only tool with strong annotations and no output schema, the description is fairly complete. It covers the two identifiers and the action. The only gap is lack of guidance on how to handle the optional parameters together, which is a minor omission given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds that they are alternative lookup keys, but does not clarify exclusivity or order of precedence when both are supplied. This does not meaningfully exceed the baseline set 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 tool's purpose: 'Retrieve a Payment Link' with two distinct lookup methods (link_id or reference_number). This specific verb+resource combination distinguishes it from sibling tools like get_checkout or get_payment_intent, which target 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?

The description indicates when to use the tool: when you have a link_id or a reference_number. It provides clear context for the intended use case. However, it does not explicitly name alternative tools for other scenarios, so it stops short of a perfect score.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds no further behavioral context, such as error cases, return format, or the meaning of openWorldHint. It merely restates the action without additional 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?

The description is a single, front-loaded sentence with no fluff. It efficiently conveys the tool's purpose 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?

For a simple getter with one parameter and strong annotations, the description is sufficient. It lacks an explicit description of the return value, but that is conventionally the resource itself, so the overall context is complete enough.

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

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

Schema coverage is 100% and the parameter description is clear. The description's 'by its ID' adds no further meaning beyond the schema, so a 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 uses a specific verb ('Retrieve'), identifies the resource ('PayMongo payment intent'), and defines the scope ('by its ID'). This clearly differentiates it from sibling tools like create_payment_intent or get_checkout.

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—you need to provide a payment intent ID to fetch it—but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety and idempotency are known. The description adds no additional behavioral context beyond what annotations provide, which is acceptable but not extra value.

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

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

The description is a single, front-loaded sentence with no filler. Every word earns its place, achieving maximum 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?

For a simple read operation with strong annotations and a clear schema, the description is largely sufficient. It could mention the return format or error behavior, but given the tool's simplicity and the annotations, it is complete enough.

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 single parameter is already described as 'Payment method ID (pm_...)' in the schema. The description only echoes 'by its ID', adding no new semantic information beyond the schema.

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

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

The description clearly states the action (Retrieve) and the resource (payment method) with a specific lookup criterion (by its ID). It is distinct from sibling tools like get_source or get_payment_intent since it targets payment methods specifically.

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

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

The description provides clear context: use this tool when you need a payment method by its ID. It doesn't explicitly mention alternatives or exclusions, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds no further behavioral context (e.g., return format, error handling, or whether a missing ID yields an error), but it does not contradict the annotations.

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

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

The description is a single, clear sentence with no filler or redundancy. It is well-structured and front-loaded with the 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?

For a simple single-parameter read operation with rich annotations, the description covers the essential purpose and invocation. It does not specify the return value or behavior when the refund is not found, but the tool's simplicity and annotation coverage make this a minor 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% with the parameter 'refund_id' described as 'Refund ID (ref_...).' The description only repeats 'by its ID' and adds no semantic nuance beyond what the schema already provides, so the 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?

The description 'Retrieve a refund by its ID' uses a specific verb ('retrieve') and a clear resource ('refund') with an identifier, distinguishing it from sibling get_* tools. It states the exact operation and scope, making the purpose unambiguous.

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

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

Usage is implied: the tool is for fetching a single refund when an ID is known. However, there is no explicit guidance on when to use this versus list_refunds or create_refund, nor any mention of alternatives or prerequisites.

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

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

The description adds no behavioral context beyond the annotations. Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description simply restates 'retrieve' without disclosing return format, error behavior, or 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?

Single sentence, direct, and free of extraneous content. It is appropriately concise for a simple one-parameter read tool.

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

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

Given the low complexity (1 param, no output schema) and strong annotations, the description is mostly sufficient. However, it lacks details about the response format or not-found behavior, which would be helpful for an agent.

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

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

Schema coverage is 100% with the source_id parameter described as 'Source ID (src_...)' . The description's 'by its ID' adds no new semantics beyond the schema, so 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 uses the verb 'Retrieve' with the resource 'payment source' and specifies 'by its ID', clearly distinguishing from sibling get tools that target other resource types. It is specific and not tautological.

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

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

No guidance is provided on when to use this tool versus other retrieval tools. It does not mention alternatives, prerequisites, or exclusions, so the agent has no context for selection.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, covering the key behavioral guarantees. The description adds no extra context about return format, error behavior, or side effects. It does not contradict the annotations, but it also doesn't enhance transparency beyond them.

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

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

A single, front-loaded sentence that states the action and resource directly. There is zero wasted content, making it highly concise and easy to parse.

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

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

For a simple get-by-ID operation with a fully documented schema and strong annotations, the description is complete. No output schema is needed since 'retrieve' implies returning the resource. The tool is simple enough that no further context is required.

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

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

The input schema has 100% coverage for the single parameter webhook_id, including an example format ('hook_...'). The description adds no additional parameter guidance. Baseline 3 is appropriate since the schema fully documents the parameter.

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

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

The description clearly states the action ('Retrieve') and resource ('a webhook'), scoped by ID. This unambiguously distinguishes it from list_webhooks and other getters like get_checkout or get_payment_intent by the resource type, even though no explicit comparison is made.

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 usage context is implied: the agent should use this when it has a specific webhook ID. However, there is no explicit guidance on when not to use it or mention of alternatives like list_webhooks. The description is minimal and doesn't provide exclusionary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds the cursor pagination behavior (before/after by customer ID), which is useful but does not go beyond that to cover response format or rate limits.

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

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

Single sentence, immediately states the action, and includes necessary pagination context without any 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?

For a simple list tool with three optional parameters fully described in the schema and strong annotations, the description is complete enough. It does not detail the return shape, but the tool's function is straightforward and the openWorldHint suggests a list response.

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

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

Schema descriptions cover 100% of the parameters with clear cursor semantics. The description reinforces 'before/after by customer ID' but adds no new information beyond what the schema already states.

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 'List' and resource 'customers', and adds the pagination method, clearly distinguishing it from get_customer (single retrieval) and create_customer.

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 pagination note implies batch retrieval, but there is no explicit guidance on when to use this over get_customer for single lookups or list_payments for other resources. Usage is implied rather than stated.

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

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

Annotations already declare read-only, idempotent, and open-world hints, so the bar is lower. The description adds the behavioral detail of cursor pagination (before/after by payment ID), which is useful, but does not disclose other traits like default ordering or response shape.

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 that immediately states the tool's purpose and the key pagination mechanism. There is no wasted text.

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

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

This is a simple read-only list tool with complete schema coverage and strong annotations. The description adequately covers pagination, and although there is no output schema, the return type (list of payments) is implied by the name. It is sufficiently complete for this tool's complexity.

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

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

Schema coverage is 100% and the parameter descriptions already explain that after/before are cursors. The description adds no additional meaning beyond what the schema provides, so the 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 lists payments, with a specific verb and resource. It also specifies cursor pagination by payment ID, which distinguishes it from other payment-related tools that retrieve single items or create 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?

The description implies use for paginated listing of payments but does not explicitly state when to use it instead of alternatives like get_payment_intent or create_payment. There is no mention of exclusions or alternative tools.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds behavioral context by specifying cursor pagination (before/after by refund ID), which tells the agent how listing is scoped. It does not describe return format, but the absence of an output schema and the read-only nature make this acceptable.

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

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

The description is a single, concise sentence that front-loads the verb and resource and adds essential pagination detail. Every word is informative; there is no filler or repetition of schema fields.

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

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

For a read-only list tool with three optional, well-documented parameters, the description provides sufficient context: it names the resource, the pagination mechanism, and the cursor keys. Annotations cover safety and idempotency, so no further behavioral disclosure is needed.

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

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

The input schema provides 100% coverage with descriptions for all three optional parameters (after, before, limit), so the description does not need to compensate. The description's mention of 'before/after by refund ID' aligns with the schema's parameter meanings but adds no new information beyond 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 identifies the action 'List' and the resource 'refunds', and specifies cursor pagination by refund ID. This distinguishes it from sibling tools like get_refund (single retrieval) and create_refund (creation), and from list_payments (different resource).

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 explicitly state when to use this tool versus alternatives, nor does it note any exclusions or prerequisites. The usage context is implied by the name and description, but no alternative guidance is 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?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds 'all registered,' but this is largely redundant with openWorldHint and the verb 'list.' It does not disclose additional behaviors such as pagination, ordering, or response format. No contradiction.

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

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

The description is a single sentence with no wasted words. It is front-loaded and appropriately sized for a simple list operation.

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 very simple with no parameters and rich annotations, but there is no output schema. The description does not mention what is returned (e.g., an array of webhook objects) or whether pagination applies. It is adequate but could be more complete for an agent.

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

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

The tool has 0 parameters, so there is nothing for the description to add. The schema is fully covered and the baseline for 0 params is 4.

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

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

The description clearly states 'List all registered webhooks,' specifying the action (list) and resource (webhooks). It distinguishes from sibling tools like get_webhook (singular) and create/update/verify operations.

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

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

The description gives no guidance on when to use this tool versus alternatives like get_webhook for a single webhook or list_payments for other resources. No context for selection is 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?

The annotation openWorldHint signals a real-world mutation, and the description aligns by saying 'update' and 'enable/disable'. It adds useful behavioral context with 'Provide any combination of url, events, enabled', which clarifies partial update semantics – an agent knows unspecified fields remain unchanged. This goes beyond the annotation, though it doesn't disclose validation 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 a single concise sentence that front-loads the action, states the resource, and lists the modifiable fields. Every word contributes, with no wasted space or repetition of the title/name.

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 simplicity of the tool (4 params, all documented, no output schema), the description is adequately complete. It covers what the tool does and partial update flexibility. It doesn't mention return values or error cases, but these are not critical for a straightforward update operation, and the schema and annotations already provide enough context.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description mentions url, events, and enabled, but does not add meaning beyond the schema's own descriptions. 'Any combination' is a slight addition, but the schema already indicates optionality. No extra syntax or constraints are provided.

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

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

The description explicitly states the verb 'update', the resource 'webhook', and the specific modifiable fields ('URL/events and/or enable/disable'). This clearly distinguishes it from sibling tools like create_webhook, get_webhook, and verify_webhook_signature.

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?

When to use this tool is implied by its name and purpose (updating an existing webhook), but it does not explicitly state alternatives or exclusions. It doesn't say 'use this instead of create_webhook for existing webhooks.' This is acceptable but not explicit, so it falls short of a 4.

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

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

The annotations already declare readOnlyHint=true, and the description adds valuable behavioral context: 'No network call' clarifies that verification is purely local, and 'uses the per-webhook signing secret you pass in' specifies the authentication mechanism. This goes beyond the annotation by detailing the operational behavior without contradicting it.

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

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

The description is two concise sentences with no fluff. It front-loads the main purpose and immediately adds the critical constraint ('No network call') and the secret context. Every word contributes to understanding the tool.

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

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

The tool has five parameters and no output schema, but the description covers the essential behavior: verification method, local execution, and secret usage. It doesn't explicitly state the return value (e.g., boolean) or error handling, which would be ideal, but the simple nature of the tool and strong schema/annotation support make this a minor 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?

The schema covers all parameters (100% coverage), so the baseline is 3. The description adds meaning beyond the schema by explaining the HMAC-SHA256 computation over 'timestamp.body', which helps understand how the signature_header and payload parameters relate. It also clarifies that the webhook_signing_secret is used locally, reinforcing the schema's note that it is NOT the API secret key.

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: locally verifying a PayMongo webhook's 'Paymongo-Signature' header using HMAC-SHA256. It is specific with a verb ('verify'), a resource ('PayMongo webhook signature'), and distinctive details (local, no network call). This clearly distinguishes it from sibling tools that create or manage webhooks.

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

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

The description provides clear context: when to use it (to verify a webhook signature) and key constraints (local, no network call, uses the per-webhook signing secret). While it doesn't explicitly name alternatives or exclusions, the context is sufficient given that no sibling tool performs signature verification.

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