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

The description adds significant context beyond annotations: it reveals the tool is one-time ('returns an API key once'), specifies it uses a public registration endpoint, and instructs on secure key storage. No contradiction with annotations (openWorldHint=true is consistent with registering a workspace).

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-load the core purpose and condition, then provide essential post-action guidance. No unnecessary words; every sentence adds value.

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

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

The description covers the return value ('API key'), the condition for use, and a warning about secret storage. No output schema exists, so the description compensates well. Missing details like exact error handling or rate limits, but acceptable for a straightforward registration tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning for individual parameters; it only provides context about the key and storage. No additional parameter semantics 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 ('Register') and resource ('Yolfi workspace') with a specific condition ('when no YOLFI_API_KEY exists yet'), distinguishing it from sibling tools that handle authentication status, organization management, or payment 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 explicitly states when to use this tool ('when no YOLFI_API_KEY exists yet') and provides post-usage guidance ('store it in an ignored env file or secret manager before using private tools'). It does not explicitly list alternatives but implies using other tools after registration.

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, destructiveHint=false, and idempotentHint=true, so the description adds value by specifying the return of 'current Yolfi organization context' and confirming the non-destructive, safe nature. However, the behavioral traits are largely covered by 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?

A single sentence that is front-loaded with the core purpose and usage context, containing no redundant words. Every part 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 zero parameters, comprehensive annotations, and no output schema, the description is fully adequate. It clearly explains what the tool does, what it returns, and when to use it, leaving no 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?

With zero parameters and 100% schema coverage, the description cannot add parameter semantics, but the baseline for no parameters is 4. The description appropriately highlights the auth-check purpose without needing parameter details.

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 verb 'Verify' and resource 'YOLFI_API_KEY can authenticate and return the current Yolfi organization context' are specific and distinct from sibling tools like yolfi_organization_get, which retrieves organization details rather than checking auth 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 states 'before mutating payment settings,' providing clear context for when to use the tool as a precondition check, which differentiates it from mutation tools in the sibling list.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the content returned (webhook and settlement configuration visible to the API key), which is not evident from annotations alone.

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

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

The description is a single, concise sentence (16 words) that front-loads the key action and content. Every word adds value, with no redundancy or filler.

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

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

Given the tool has no parameters and rich annotations (readOnly, idempotent), the description covers the purpose and scope well. It lacks details about the return format, but for a simple read operation without output schema, it is sufficiently complete.

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

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

The input schema has zero parameters, so the description need not add parameter details. Schema coverage is 100% trivially. The description does not need to compensate, so a baseline of 4 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 reads organization settings, specifying 'webhook and settlement configuration visible to this API key.' It uses a specific verb ('read') and resource ('organization settings'), and distinguishes itself from sibling tools like yolfi_organization_update by implying a read-only operation.

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

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

No explicit guidance on when to use this tool versus alternatives is provided. The context implies it is for inspecting current settings before making changes, but the description does not state when-not-to-use or mention 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description does not disclose whether the update is partial or full, confirmation behavior, or consequences. The caution is a constraint, not a behavioral disclosure.

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: one clear purpose statement and one caution. Both are front-loaded and contain no filler. 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 4 optional parameters, no output schema, and annotations, the description provides basic purpose and a caution but lacks details on response, partial update behavior, or effect of omitted fields. Adequate but not thorough.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds no further meaning to the parameters beyond the schema, such as format or defaults. 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 title and description clearly state 'Update Yolfi Organization' and 'Update organization profile fields', with a specific verb and resource. The caution about not inventing fields adds clarity and distinguishes it from related tools like yolfi_organization_get.

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 explicit guidance on when to use this tool versus alternatives such as yolfi_organization_get or yolfi_settlement_configure. It only cautions against inventing fields, which is not a usage guideline.

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

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

Annotations are sparse (readOnlyHint, destructiveHint, idempotentHint all false, openWorldHint true). The description only adds the approval requirement, but does not disclose other behavioral traits like idempotency, error behavior, or authority needs. For a creation tool, more context is needed.

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

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

The description is a single clear sentence that is front-loaded with the main action. It is concise and to the point, though slightly more structure could improve readability.

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

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

Given the tool has 8 parameters (including nested objects) and no output schema, the description is minimal. It does not explain return values, what happens if recurringInterval is provided for ONE_TIME, or other important context. Incomplete for the complexity level.

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

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

Schema coverage is 100% (all parameters with descriptions). The description text adds 'user-approved' context but does not provide additional meaning beyond what the schema already says. Baseline 3 is appropriate.

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

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

The description clearly states it creates a Yolfi payment link, which is a specific verb+resource. The name already distinguishes it from siblings like 'yolfi_paylinks_disable'. However, it could be more explicit about what a paylink is, but the 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?

The description explicitly states a precondition: 'only after the user approves...', which guides when to use the tool. It implies not to use it without prior approval, but does not explicitly mention alternatives or when not to use it.

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

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

Annotations already set destructiveHint=true and readOnlyHint=false. The description adds crucial context: 'This is destructive and must only run after explicit user confirmation,' emphasizing the need for user confirmation beyond the annotation.

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

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

Two short sentences, each earning its place. The first sentence states the action; the second adds critical safety instruction. No wasted words.

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

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

Covers the action, destructive nature, and confirmation requirement. Could mention the outcome (e.g., the paylink becomes inactive) or return value, but overall sufficient for a disable operation.

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

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

Schema coverage is 100% with both parameters described. The description does not add extra meaning beyond the schema, but the schema is clear. 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 title 'Disable Yolfi Paylink' and description 'Disable a paylink' clearly state the action and resource. The tool is distinct from sibling tools (no other disable tool).

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

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

The description explicitly states it is destructive and requires explicit user confirmation. However, it does not mention when to use this tool vs. alternatives (e.g., yolfi_paylinks_list or yolfi_paylinks_get).

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, destructiveHint=false, and idempotentHint=true, which cover safety and idempotency. The description adds the context that details are 'private', implying access control considerations, but does not elaborate further on behavioral traits such as rate limits or required permissions. It adds minimal value beyond 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 of 13 words, front-loading the action and identifier, and then listing three use cases. Every word serves a purpose; there is no fluff. It is maximally concise while still providing essential context.

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

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

For a simple retrieval tool with one well-described parameter and safety annotations, the description covers the key aspects: what it does, what input to provide, and when to use it. There is no output schema, so the agent might need to infer the return format, but the use cases given help set expectations. It is largely complete for its complexity level.

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

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

The input schema covers the single parameter 'id' with 100% description coverage, stating it is a Yolfi paylink ID from other tools. The tool description does not add extra semantic information about the parameter beyond what the schema provides. Given the full schema coverage, a 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 ('Get'), identifies the resource ('private paylink details'), and specifies the identifier ('by ID'). It also lists three distinct use cases (verification, checkout wiring, duplicate detection), which clearly differentiates it from sibling tools like yolfi_paylinks_list (list all) and yolfi_paylinks_create (create new).

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 when to use this tool: for verification, checkout wiring, or duplicate detection. This provides clear context. However, it does not explicitly state when not to use it or mention alternatives, though the sibling tools are listed separately. The guidance is strong but not exhaustive.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context about retries and timeouts, which is valuable beyond the annotations. 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?

Single sentence that is front-loaded with the action and use case, with no redundant words. Highly concise and well-structured.

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

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

Despite good purpose clarity and usage guidance, the description does not explain the output format or what the response contains. Since there is no output schema, this is a notable gap for a list 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 both parameters described (page, rows with defaults). The description does not add any parameter-specific information, 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 (list existing Yolfi paylinks) and the resource, with a specific use case (before creating new ones to avoid duplicates after retries or timeouts). This distinguishes it from siblings like yolfi_paylinks_get.

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 when to use the tool (before creating new paylinks), providing good context. However, it does not mention when not to use it or suggest alternatives, though the context is clear enough.

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

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

Annotations already indicate mutability (readOnlyHint=false), non-destructiveness (destructiveHint=false), and side effects (openWorldHint=true). The description adds minimal behavioral context beyond 'create', which is consistent. It does not elaborate on side effects, reversibility, or required permissions, so it adds little beyond the annotations.

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

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

A single efficient sentence (14 words) that is front-loaded with the action. Every word adds value, with no redundancy or fluff.

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

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

Given 5 parameters (including nested metadata with no allowed structure explained), no output schema, and openWorldHint, the description is minimal. It informs the basic purpose and use cases but omits details about return values, metadata constraints, or the meaning of 'public payment invoice'.

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

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

Schema coverage is 100%, so baseline is 3. The description does not provide additional meaning for parameters beyond what the schema already includes (e.g., 'paylinkId' is described as existing, but details like format are in schema). No extra param-specific guidance is given.

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

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

Clearly states it creates a public payment invoice from an existing paylink, with explicit use cases (checkout, testing, customer flow). The verb 'Create' and resource 'payment invoice' are specific, and the description distinguishes it from siblings like yolfi_payments_status (status check) and yolfi_paylinks_create (creates paylinks).

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 context for when to use (from an existing paylink for checkout/testing/customer flow) but lacks explicit guidance on when not to use or alternatives. No comparison to sibling tools is given, so the agent must infer usage from the description 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?

Adds behavioral context beyond annotations (readOnlyHint, etc.) by warning against relying on frontend redirects, clarifying the need for server-side verification.

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, directly state purpose and key warning, no filler.

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

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

Covers purpose and a critical usage caveat; lacks details about the response format (status values), but acceptable for a simple read tool with no 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 description coverage is 100%, so the description adds minimal value beyond the schema's parameter documentation; 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 tool retrieves public payment status by ID (specific verb+resource) and is distinct from sibling tools like yolfi_payments_create or yolfi_auth_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?

The warning 'Do not treat a frontend redirect as proof of payment' provides critical usage guidance, but does not explicitly mention when to use this over alternatives or specify 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?

Annotations indicate non-readOnly, non-destructive, non-idempotent, and open-world. The description adds that it configures wallets and forbids inventing addresses. It does not elaborate on side effects, reversibility, or return behavior, which would enhance 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 very concise: two sentences front-loaded with purpose. It includes a crucial constraint without unnecessary detail. Every sentence adds value.

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

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

For a simple tool with one required parameter and no output schema, the description covers the main purpose and a key rule. However, it does not mention what happens on success or failure, or if there are prerequisites beyond user input (e.g., authentication via yolfi_auth_status).

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 a description for the parameter 'settlementAccounts' with example fields. The description's mention of wallet addresses, networks, and enabled tokens echoes this but does not add significant new meaning beyond the schema. With 100% schema coverage, 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 verb 'Configure' and the resource 'settlement wallets', and specifies that it should be used after the user provides wallet addresses, networks, and enabled tokens. This distinguishes it from sibling tools like yolfi_organization_update which is more general.

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 some usage guidance by stating 'after the user provides wallet addresses, networks, and enabled tokens' and the rule 'Never invent wallet addresses.' However, it does not explicitly mention when not to use this tool or compare it to alternatives among 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 indicate non-read-only and non-idempotent behavior. The description adds context: it configures webhook delivery and emphasizes that the URL must be real and the app must verify signatures, which is beyond what annotations convey.

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, no fluff, front-loaded with the purpose. Every sentence adds value.

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

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

Given the low complexity (2 parameters, no output schema, good annotations), the description sufficiently covers what the tool does and critical constraints. It is complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% and parameters are well-described in the schema. The description adds some meaning for the 'url' parameter by stating 'must not invent backend URLs', but says nothing about 'adapter.' Baseline 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 'Configure' and the resource 'webhook delivery for the target app.' It distinguishes from sibling tools such as 'yolfi_webhooks_verify' by specifying configuration rather than verification.

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 important usage guidance: 'The host must not invent backend URLs' and 'must ensure the app verifies X-Yolfi-Signature.' While it does not explicitly compare to siblings, it gives clear constraints for correct 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it performs HMAC verification, which is a specific behavioral trait. It does not detail failure modes but is consistent with annotations.

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

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

A single concise sentence that front-loads the action and purpose. No extraneous 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?

The description adequately explains the tool's role for a verification operation with complete parameter documentation and clear annotations. Missing output schema is acceptable for a simple verification 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 clear descriptions for all three parameters. The tool description adds no additional parameter information, so it meets the baseline without further elaboration.

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 tool name and title clearly indicate verification of webhook signatures. The description specifies the exact action (verify HMAC over raw JSON payload) and the context (payment events), distinguishing it from sibling tools like yolfi_webhooks_configure.

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 (before trusting payment events), providing clear context. It does not explicitly exclude scenarios or mention alternatives, but the sibling list makes differentiation straightforward.

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