PassFast

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

Without a rich annotation set, the description carries the behavioral burden and does so thoroughly: synchronous execution, per-row semantics, billing 402 behavior with stopped_reason, partial-failure continuation, and the exact HTTP statuses for limit, auth, and template errors. There is no contradiction with 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 long but organized into scannable bolded sections (Auth, Body, Limits, Billing, Partial failures) and front-loads the core purpose. A few statements, such as the host details and OpenAPI mapping, are redundant for MCP usage, but they do not obscure the essential behavior.

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?

Even without an output schema, the description covers what an agent needs to invoke the tool correctly: auth methods, request body alternatives, limits, error codes, partial-success semantics, billing outcomes, and the shape of the response. This is comprehensive for a nested, 7-parameter mutation 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 86%, so the baseline is already high. The description adds real value by explaining how rows, csv, and column_map interact ('do not send both'), how create_share_links triggers a follow-up request, and how X-App-Id should be handled for multi-app orgs.

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 leads with a specific verb and resource: it batch-generates wallet passes, up to 100, in one synchronous request. It also frames each accepted row as one POST /generate-pass, which distinguishes it from the single-pass sibling generatePass.

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 clear operating context: batch size, supported body formats, the requirement to choose either rows or csv, and when create_share_links applies. It does not explicitly say 'use generatePass for a single pass,' so it lacks an explicit alternative exclusion, but the role 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?

The description adds meaningful behavior beyond annotations, especially that the `raw_key` is shown only once and cannot be retrieved again. It also discloses the required scope, rate-limit context, and that the tool maps to a specific HTTP endpoint, which helps the agent anticipate side effects and constraints.

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

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

The description is reasonably concise and front-loads the core purpose and critical one-time-key warning. Minor redundancy exists between the title 'Create an API key' and the first sentence, but the additional endpoint and scope details earn their place.

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

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

With no output schema, the description compensates by listing the response fields and explaining the unrecoverable raw key. It also covers scope, endpoint mapping, and operational constraints, so an agent has enough context to invoke the tool correctly without inventing details.

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 input schema already fully documents both `name` and `key_type`, including the enum values. The description adds no additional parameter-level meaning, matching the baseline expectation when the schema carries the full burden.

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 ('Creates a new API key') and resource, distinguishing it from sibling create tools like createApp and createTemplate. It also anchors the tool to a concrete OpenAPI operationId and endpoint, leaving no ambiguity about what it 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 usage context is implied by the action itself and reinforced by the scope (`org:manage`) and endpoint mapping. However, it does not explicitly explain when to choose this over related alternatives like listApiKeys, revokeApiKey, or deleteApiKey, and there are no exclusions or sibling comparisons.

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 behavioral context beyond the annotations by specifying the required scope (org:manage), the exact HTTP mapping (POST /manage-org/app), and that the same PassFast billing and rate limits apply. It does not contradict the readOnly, destructive, or idempotent hints, and it credibly explains the operation's access and API characteristics.

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 compact and well-structured with bold labels and a clear endpoint mapping. The opening line 'Create a new app' is somewhat redundant with the following sentence, but the rest of the content is focused and front-loaded with essential scope and path 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 simple one-parameter creation tool with no required parameters, the description covers the essential scope, path, and API constraints. It does not describe the response shape or error behavior, but the absence of an output schema and the low complexity make the provided context reasonably complete for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the single 'name' parameter is already documented as 'App display name' with a default. The tool description does not add any additional parameter semantics, 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 verb 'Create' and the resource 'a new app within the organization,' so an agent can tell this is for creating an app resource. It is specific and accurate, but it does not explicitly distinguish itself from sibling create* tools, so it stops short of the highest clarity score.

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

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

The description gives useful operational context: the org scope, the OpenAPI operationId, and the POST path. It implies that this tool is used when creating an app, but it does not explicitly state when to prefer this over alternatives or when not to use it, so the usage guidance is more implied than explicit.

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

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

The description goes beyond the annotations by explaining what idempotency means in practice (existing token returned with 200 instead of 201) and the automatic application to sibling passes for dual-wallet scenarios. It also discloses the required scope and notes that the same API, billing, and rate limits apply. This adds useful context that the annotations alone do not provide.

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

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

The description is well-structured with a clear lead sentence followed by focused details. Each paragraph adds necessary information: idempotency, dual-wallet handling, scope, and API context. There is no fluff; every sentence contributes to understanding how to use the tool correctly.

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

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

For a mutation tool with no output schema, the description covers all critical behavioral aspects: idempotency, dual-wallet sibling propagation, required scope, rate limits, and endpoint mapping. An agent can confidently invoke this tool without missing information needed to make a correct call.

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 does not add any additional parameter semantics beyond what the schema provides, but it also does not need to. It correctly relies on the schema, which is the baseline expectation.

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

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

The description clearly states the action (create a share token), the resource (a pass), and the purpose (enabling distribution via URL, QR code, or messaging). It is specific and distinguishes itself from other share-related operations like downloadSharedPass or getSharePassMetadata by focusing on token creation. The endpoint mapping and scope further clarify its unique role.

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

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

The description explains when to use the tool: to create a public share token for a pass. It also covers idempotency and dual-wallet behavior, which informs the agent when it might reuse an existing token. However, it does not explicitly contrast with sibling tools or state when not to use it, though the context is strong enough to infer.

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

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

Beyond annotations (which only mark mutation/non-idempotence), the description adds valuable behavioral context: the result is a draft-status template, the required scope is templates:manage, and the operation maps to a single known HTTP endpoint with shared billing/rate limits. It also warns not to invent alternate paths. It does not describe what the response contains or how a draft becomes published, but annotations already flag the mutation profile.

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

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

The description is short and front-loaded, with useful scoping and endpoint guardrails in the final lines. The only waste is the redundant first line 'Create a template' immediately followed by the same statement; otherwise every sentence 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?

This is a high-complexity create operation with 15 parameters, deep nested structure, and no output schema, yet the description provides no lifecycle context beyond 'draft status' and no indication of the response shape or how to reference the created template afterward. The scope and endpoint info is useful but not sufficient for an agent to fully understand the consequences of the call.

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 description adds no parameter-level meaning, and schema coverage is only 47% (below the 50% threshold), so the description was expected to compensate for undocumented structure fields. Required fields like name, pass_style, and structure are discoverable from the schema, but many nested properties and image/override parameters remain unexplained by both the schema and the description.

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

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

The description opens with a clear verb and object and specifies a unique state: 'Creates a new pass template in draft status.' This distinguishes it from updateTemplate, publishTemplate, and listTemplates, and the explicit OpenAPI operationId and POST /manage-templates mapping leave no ambiguity about the intended action.

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 through 'create' and 'new', but the description never states when to choose this over siblings or when not to use it. It does provide useful preconditions (templates:manage scope, same API billing/rate limits), so there is some guidance beyond pure tautology.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description's 'Deactivates' is consistent. It adds scope and API mapping, but does not disclose side effects (e.g., irreversible invalidation) or any additional behavioral nuance beyond what annotations provide. 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?

Extremely concise: a single action sentence plus three short lines of essential context (scope, API mapping, caution). No redundant text; the most important information is front-loaded.

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

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

For a simple deactivation operation with full schema and relevant annotations, the description provides adequate context: scope, API mapping, and a warning against inventing paths. Could mention reversibility or effects on the credential, but that is not critical given the operation is destructive by definition.

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 covers both parameters at 100% (id and x_app_id), including descriptions and required flag. The description adds no extra parameter-level detail, so baseline 3 is appropriate; it does not need to compensate for schema gaps.

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

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

Description clearly states it deactivates a Google Wallet credential, includes scope (certs:manage) and maps to a specific OpenAPI operationId, distinguishing it from sibling tools like deleteCertificate or revokeApiKey. The verb and resource are 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?

Provides API context (same PassFast HTTP API, billing, rate limits) and a caution not to invent paths, but does not explicitly compare to alternatives or state when to use this vs other deletion tools. Selection guidance is implied by the action name but not made explicit.

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 mark destructiveHint=true, and the description adds meaningful behavioral detail: permanent deletion, the revoke-first prerequisite, the 400 error for active keys, the org:manage scope, and the exact endpoint. There is no contradiction with annotations.

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

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

The description is front-loaded with the core action, then compactly covers preconditions, scope, endpoint mapping, and guardrails. Each sentence earns its place, and bold/paragraph structure makes it scannable without redundancy.

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

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

For a one-parameter destructive action with annotations already present, this is complete: the agent knows the effect, the prerequisite, the failure mode, the required scope, and the exact HTTP path. No output schema is necessary for a simple delete operation.

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

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

The schema fully documents id as a UUID API key ID, and the description adds extra meaning by explaining the id must reference a revoked key and that it appears as {id} in the DELETE path. This goes beyond the schema's bare field description.

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

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

The description states a specific verb and resource ('Delete an API key' / 'Permanently deletes an API key') and distinguishes itself from revokeApiKey by requiring the key to be revoked first. The explicit DELETE /manage-keys/{id} mapping removes any ambiguity about which operation this is.

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

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

It provides clear usage context: only a revoked key can be deleted, and attempting to delete an active key returns 400. This implies the revoke-then-delete workflow, though it does not explicitly name the sibling revokeApiKey as the alternative or state 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent expects a state-changing action. The description adds valuable nuance by clarifying that this is not permanent deletion ('does not permanently delete data'), which prevents over-interpretation of destructiveHint. It also discloses the required auth scope and the policy constraint not to invent alternative paths—useful context 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?

The description is compact and front-loaded: the one-line summary is immediately followed by the most important caveat (non-permanence), then scope and API mapping. Every sentence earns its place—there is no filler or repetition of schema content.

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

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

For a simple tool with one optional parameter and no output schema, the description covers safety (non-destructive nuance), auth scope, endpoint mapping, and usage constraints. The only slight gap is that 'the current app' is not fully defined in the description itself, though the parameter schema clarifies how to target a specific app in multi-app orgs.

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

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

Schema description coverage is 100%: the only parameter `x_app_id` is fully documented in the schema with guidance on when to set it ('multi-app orgs'). The tool description itself adds no extra parameter-level detail, so it does not compensate beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description clearly states the action ('Deactivate an app') and the specific resource ('the current app'), and immediately adds a crucial distinction from deletion: 'This does not permanently delete data.' This differentiates it from sibling delete* tools (e.g., deleteApiKey, deleteTemplate) and clarifies the operation's intent. The mapping to operationId `deleteApp` and DELETE /manage-org/app reinforces the purpose.

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

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

Provides clear context: it acts on 'the current app', requires scope `org:manage`, and points to the exact HTTP path. It also warns 'Do not invent other paths' and notes shared billing/rate limits. However, it does not explicitly say when to choose this tool over alternatives like updateApp or getApp, or describe when deactivation is preferable to other lifecycle operations.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns with that. The description adds useful context about the required scope, the exact API path, and that the same PassFast HTTP API, billing, and rate limits apply. It also warns not to invent other paths, which is helpful for an agent.

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

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

The description is concise and front-loaded with the core action, then provides essential context in a few short lines. Every sentence adds value: the action, the scope, the operation mapping, and the warning about not inventing paths.

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

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

For a destructive single-resource operation with a simple schema and no output schema, the description is largely complete. It covers the action, scope, endpoint, and operational constraints. It could mention the return value or error behavior, but the annotations and schema already cover the safety profile and parameters.

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 does not add extra parameter-level detail beyond the schema, but the baseline of 3 is appropriate because the schema carries the full burden.

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 deletes a certificate, identifies the exact OpenAPI operationId and HTTP endpoint, and specifies the required scope. This distinguishes it from sibling tools like uploadCertificate and listCertificates.

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 the required scope and notes that it maps to a specific OpenAPI operation, which helps an agent understand when to use it. It does not explicitly name alternatives or state when not to use it, but the scope and endpoint mapping give clear context.

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

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

Goes well beyond the destructiveHint annotation by disclosing exact side effects: template columns are silently cleared, pass strip overrides are nullified, deletion always succeeds when the image exists, and the operation requires images:manage scope. The description is consistent with annotations, so 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 front-loaded with the core action and then details consequences, preflight guidance, scope, and API mapping. It is slightly repetitive ('Delete an image' / 'Deletes an image'), but every sentence contributes actionable information.

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

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

For a destructive operation with no output schema, it tells the agent what gets destroyed, what cascading effects occur, how to assess blast radius, what scope is needed, and which HTTP operation it maps to. Missing return-value details are minor given the behavioral coverage.

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

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

Schema description coverage is 100%, so the schema already documents id and x_app_id. The description adds no extra parameter-level meaning, which matches the baseline of 3 for high schema coverage.

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

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

States a specific verb and resource: 'Delete an image' and clarifies it deletes both 'storage file + DB row'. This distinguishes it cleanly from siblings like uploadImage, listImages, and getImageUsage.

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

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

Provides clear operational guidance: it tells the agent to call GET /manage-images/{id}/usage first when blast radius matters, and notes the scope requirement. It does not explicitly contrast itself with sibling delete tools, but the guidance is contextually sufficient.

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

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

Beyond the annotations' destructive hint, the description reveals that deletion is actually a soft archive by default, that `permanent=true` removes the template and its associated data, and that the operation requires `templates:manage` scope. This adds meaningful behavioral context that annotations alone do not provide, with 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 concise and front-loaded with the primary action, followed by the key behavioral option and operational context. Some sentences, such as the OpenAPI mapping and the generic API/rate-limit note, are slightly redundant with sibling context, but they earn their place by reinforcing correct invocation.

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

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

For a destructive operation with only one required parameter, the description covers the operation path, auth scope, default behavior, permanent-deletion behavior, and guardrail against invented paths. It doesn't describe the response format or error cases, but given the absence of an output schema and the tool's simple parameter set, the description is sufficiently complete for correct invocation.

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

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

The input schema already documents all three parameters, so the baseline is 3. The description adds value by explaining the semantic distinction between archiving and permanent deletion and emphasizing that permanent deletion affects associated data, which goes beyond the schema's parameter descriptions.

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

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

The description clearly identifies the resource ('template'), the verb ('Delete'), and the two behavioral modes (soft archive vs permanent deletion). It also maps to a specific OpenAPI operation and endpoint, making the tool's purpose unambiguous and distinct from sibling operations like updateTemplate or publishTemplate.

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 explicit contextual guidance: soft-deletes by default, and tells the agent to use `permanent=true` for permanent deletion. It also states the required scope (`templates:manage`) and cautions against inventing other paths. It doesn't explicitly name when to prefer an alternative sibling, but for a delete operation the provided 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?

Beyond the readOnly/idempotent annotations, the description adds useful behavioral context: the output is a binary `.pkpass` file, the operation is scoped to `passes:download`, and the same billing and rate limits apply. It also warns against inventing other paths, which is valuable for an AI agent. It does not describe failure behavior for inactive passes, but annotations already cover the safety profile.

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

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

The description is mostly tight and front-loaded, with the key action stated immediately. The first sentence 'Download a .pkpass file' is somewhat redundant with the second sentence 'Downloads the `.pkpass` binary...' but the overall length is still appropriate. The endpoint mapping and anti-hallucination note are useful and earn their place.

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

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

For a simple download operation, the description covers the essential context: what is downloaded, for what kind of pass, under what scope, and through which endpoint. The lack of an output schema is mitigated by stating the binary nature of the response. It could be more complete by addressing inactive-pass error behavior, but nothing critical is missing for a safe call.

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 full description coverage for both `id` and `x_app_id`, so the description does not need to repeat parameter details. The description mentions 'active pass' but does not add new semantics to the parameters beyond what the schema documents. This matches the baseline for high schema coverage.

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

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

The description clearly states a specific action and resource: downloading the `.pkpass` binary for an active pass. It also maps to a concrete endpoint, which removes ambiguity about the operation. However, it does not explicitly contrast itself with sibling tools like `downloadPassBySerial` or `downloadSharedPass`, so differentiation is only inferred from the path and parameter schema.

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 active passes and identifies the exact endpoint, but it does not explicitly state when to prefer this over alternatives. There is no when-not-to-use guidance or mention of sibling tools. The 'active pass' condition and the `{id}` path provide only implied usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description adds value by declaring the auth scope (`passes:download`), the exact GET endpoint, and billing/rate-limit parity. The guardrail 'Do not invent other paths' adds a useful constraint beyond the structured fields. No contradiction with the read-only 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?

Every line earns its place: the one-line purpose summary, the wallet disambiguation, the scope, the OpenAPI mapping, and the billing/rate-limit guardrail. It is compact, logically grouped, and front-loaded with the core action.

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

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

With all three parameters fully documented in the schema and annotations carrying the safety profile, the description covers the return format (the .pkpass binary) and the active-pass constraint. It doesn't describe error behavior for unknown or inactive serials, which is a minor gap for a no-output-schema tool.

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

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

Schema description coverage is 100%, so the baseline is 3; the description restates the wallet_type disambiguation that the schema already documents in detail. No additional semantics are added for serial_number or x_app_id beyond what the schema provides.

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

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

The opening line 'Download a .pkpass file by serial number' names a specific verb, resource, and lookup key, and the description adds that it applies to an 'active pass.' This differentiates it from siblings like downloadPass (presumably by pass ID) and getPassBySerial (metadata, not the binary).

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 clear context for the wallet_type parameter — use it when a serial has both Apple and Google passes, defaulting to apple — but never names sibling tools or states when to choose this over getPassBySerial or downloadPass. Usage relative to alternatives is only implied by the phrase 'Download the .pkpass binary.'

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 mark it read-only, idempotent, and non-destructive; the description adds the exact endpoint mapping (GET /share-pass/{token}/download), the public/no-auth behavior, the active-pass prerequisite, and a warning not to invent other paths. This is substantive behavioral context beyond the hints.

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 compact and front-loaded, but it has minor redundancy: the opening line repeats the first sentence, and 'no authentication required' appears twice. This is a small efficiency issue rather than a structural problem.

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 one-parameter public download with no output schema, the description covers the endpoint, auth profile, prerequisite, and rate-limit context. It does not spell out failure modes for expired or inactive tokens, but that is a minor gap given the tool's simplicity.

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

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

The schema already fully documents the single required token parameter, including its format as 32 hex characters. The description only repeats token in the path template and adds no new semantic meaning, so the 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?

Opens with a specific verb and resource ('Download shared Apple .pkpass') and the body confirms it downloads the .pkpass file for a shared pass. It also signals the distinguishing dimension—public, no-auth endpoint—so an agent can separate it from sibling download tools.

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

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

Provides clear context: use for shared passes with a share token, only when the pass is active, and without authentication or an API key. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full alternative routing.

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

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

The description goes far beyond the annotations by explaining response formats for Apple, Google, and both; partial success behavior; X-Pass-Id and X-Pass-Existed headers; webhook invocation, rejection, and fail-closed error mapping; and the meaning of 201/200/403/502 statuses. This is rich behavioral disclosure for a mutating operation with external webhook side effects, consistent with openWorldHint and idempotentHint false.

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 dense but well organized, with the core generation behavior front-loaded and wallet-specific variants, headers, webhook behavior, and API mapping following in logical order. Each sentence adds distinct information, from response format to failure behavior to operational scope. The slight repetition of 'Generates a wallet pass' is minor and does not hurt usability.

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

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

Given the high parameter count, nested objects, absence of an output schema, and complex wallet/webhook behaviors, the description is exceptionally complete. It specifies return values for all wallet_type modes, status codes, headers, error paths, and the required OAuth scope. An agent has enough context to invoke the tool correctly and interpret the response without additional documentation.

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 all parameters are documented in the schema, but the description adds meaningful behavioral context for wallet_type, get_or_create, strip_image_id, and response headers. It clarifies partial success semantics for 'both' and the X-Pass-Id header, which are not fully obvious from the schema alone. It does not exhaustively explain every parameter, but the schema already handles the 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 description states a specific verb and resource: 'Generate a wallet pass' from a published template. It distinguishes output formats by wallet type and clearly differentiates this creation operation from sibling read/update/download tools like getPass, downloadPass, and updatePass. The OpenAPI operationId and POST /generate-pass mapping further disambiguate it.

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 clear context on when to use the tool: to generate a wallet pass from a published template, with explicit wallet-type behavior. It does not explicitly name alternatives or exclusions, but the scope and detailed response semantics make the intended usage unambiguous. The 'Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.' note also provides practical guardrails.

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 mark it read-only, idempotent, and non-destructive. The description adds value by declaring the org:read scope, the exact OpenAPI operationId/path, and the fact that the same HTTP API, billing, and rate limits apply, plus a guard against inventing other paths.

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 compact and front-loaded: the purpose is in the first line, and the remaining lines are short, distinct facts about scope, endpoint mapping, API behavior, and a constraint. No sentence is redundant.

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 low-complexity read with one optional, fully documented parameter and safety annotations, the description covers scope, endpoint, and API constraints. It does not enumerate the return fields in 'app settings,' and there is no output schema, which is the only notable 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 description coverage is 100%, and the schema already explains x_app_id fully (override the header, omit by default, set only for multi-app orgs). The description adds no parameter-level detail, so the baseline score 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 states a specific verb and resource ('Get current app details') and clarifies the output ('Returns the current app's settings'). It also pins the operation to GET /manage-org/app, which distinguishes it from sibling tools like getOrganization and getTemplate.

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 intended use is implied by 'current app details' and the org:read scope, and the path mapping provides operational grounding. However, it does not explicitly name alternatives or state when not to use this tool, so an agent has to infer selection from the purpose line.

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, so the safety profile is covered. The description adds valuable context: it is public metadata, requires no API key, and returns specific fields (row cap, sync mode, auth summary, error codes). It also notes the same rate limits apply, which is useful behavioral context 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?

The description is compact and front-loaded with the core purpose. It includes necessary routing and authentication details without excessive verbosity. Minor redundancy exists in repeating the operationId and endpoint mapping, but the overall structure is efficient.

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

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

For a parameterless public metadata endpoint, the description is complete: it states the purpose, the exact path, the host, authentication requirements, and the return fields. The annotations cover safety and idempotency, and no output schema is needed for this simple metadata response. Nothing essential is missing.

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

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

The tool has zero parameters, so the schema is trivially complete. The description adds meaning by explaining what the endpoint returns, which is the relevant semantic content for a parameterless metadata tool. A baseline of 4 is appropriate for a zero-parameter tool.

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: it returns public metadata for POST /passes/batch, including the hard row cap, sync mode, auth summary, and stable error codes. It names the specific resource and endpoint, and the sibling list confirms it is distinct from batchGeneratePasses and other tools.

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

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

The description explicitly says this is a public endpoint with no authentication required, and it clarifies the correct host path, distinguishing it from the functions host. It also instructs the agent not to invent other paths, which is strong usage 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 annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is to add behavioral context, which it does thoroughly. It explains the meaning of returned fields (template_refs, pass_refs_count, safe_to_delete), the safe_to_delete condition, the required scope, the OpenAPI mapping, and rate-limit behavior. This goes well 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?

The description is well-structured: a one-line summary followed by a purpose sentence, a bulleted list of output semantics, and a concise scope/endpoint note. Every section earns its place, and the key behavioral info is front-loaded. There is 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?

With no output schema present, the description takes on the burden of explaining return values, and it does so clearly: template_refs, pass_refs_count, and safe_to_delete are all defined. Combined with the use-case guidance, scope, endpoint mapping, and parameter coverage, an agent has everything needed to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents both id and x_app_id. The description adds no additional detail about the parameters themselves, so 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 opens with a specific verb and resource ('Get image usage / reference counts') and then elaborates with a clear statement: 'Report how an image is referenced across templates and passes.' This clearly distinguishes it from sibling tools like deleteImage or listImages by focusing on reference counts rather than direct image 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 the tool: 'Useful before DELETE to confirm an image is unused, or to find which templates a shared asset is attached to.' This gives clear usage context, though it does not explicitly name alternative tools or state 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 declare the operation read-only, idempotent, and non-destructive. The description adds useful context beyond those annotations by stating the org:read scope, mapping to the exact GET endpoint, and returning readiness flags that influence signing modes. This is transparent and consistent with 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 compact and well-structured: the purpose is stated first, followed by behavioral implications, scope, and endpoint mapping. Every sentence adds meaningful information, and there is no redundant or filler content.

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

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

For a zero-parameter read-only status check, the description is complete. It explains the return semantics, the conditions that affect downstream usage, the required scope, and the exact API mapping. Even without an output schema, an agent knows what to expect from the 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?

The tool accepts no parameters, and schema description coverage is 100%, so the schema leaves nothing ambiguous. The description still adds value by explaining what the response fields mean, even though it does not need to document parameters.

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

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

The description clearly states the tool checks managed signing availability for Apple and Google wallets and explains the meaning of the returned fields. It does not explicitly differentiate itself from sibling tools like testAppleCertificates or testGoogleConnection, but the resource and behavior are specific enough to avoid confusion.

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

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

The description gives a clear use case: checking whether managed signing credentials are available so apps can use signing_mode: 'managed'. It does not explicitly mention alternatives or exclusions, so it falls short of a 5, but the context is sufficient for an agent to select this tool.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the exact API path, org:read scope, rate-limit/billing alignment, and a warning not to invent other paths.

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 short, front-loaded with the purpose, and every sentence contributes information: resource, scope, OpenAPI mapping, and API constraints. There is no redundant or filler content.

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

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

For a zero-parameter read-only operation, it covers the endpoint, scope, and rate-limit constraints, which is sufficient for selection and invocation. It does not enumerate the specific settings fields returned, but those are not required to call the tool correctly.

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

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

The tool takes zero parameters and schema coverage is 100%, so there is no parameter information for the description to add. Per baseline for zero-parameter tools, this is appropriately handled.

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

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

The description opens with 'Get organization details' and clarifies it 'Returns the current organization's settings,' giving a specific verb, resource, and scope. It also maps to GET /manage-org, which distinguishes it from sibling getters like getApp and getPass.

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 intended use is implied by the resource name and description, but there is no explicit when-to-use or when-not-to-use guidance versus alternatives. The 'Do not invent other paths' caution is a constraint, not a routing decision.

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, so the safety profile is covered. The description adds useful behavioral context: it returns full details, requires the passes:read scope, and explicitly warns against inventing other paths. It does not describe pagination or error behavior, but for a single-resource GET with strong annotations, this is adequate.

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

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

The description is compact and front-loaded: the first line states the action, then the return value, scope, operationId, and a clear warning. Every sentence earns its place, and there is no redundant filler.

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

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

For a simple single-resource GET with 2 parameters, 100% schema coverage, and strong annotations, the description is nearly complete. It covers scope, HTTP mapping, and a caution about not inventing paths. It could mention the response format, but no output schema exists and the description already says 'full details,' which is sufficient for an agent to invoke it 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 description coverage is 100%, so the schema already documents both parameters ('id' and 'x_app_id'). The description adds a small amount of context by mentioning the HTTP path and scope, but it does not elaborate on parameter semantics beyond what the schema provides. 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 states a specific verb ('Get') and resource ('a single pass'), and explicitly says it returns 'full details of a single pass.' It also names the OpenAPI operationId and HTTP path, which distinguishes it from siblings like getPassBySerial, downloadPass, and listPasses. The scope line ('passes:read') further clarifies its read-only purpose.

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

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

The description provides clear context: it maps to GET /manage-passes/{id}, states the scope, and notes that it shares the same PassFast HTTP API, billing, and rate limits. It also warns 'Do not invent other paths.' However, it does not explicitly contrast with alternatives like getPassBySerial or listPasses, so an agent must infer when to choose this over those siblings.

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

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

The annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds useful behavioral context: the default wallet_type is `apple`, the scope is `passes:read`, and it maps to a specific GET endpoint with normal PassFast API billing and 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?

The description is front-loaded with the core purpose and then adds relevant usage details about wallet_type, scope, and endpoint mapping. The operational caveats about billing and not inventing paths are somewhat boilerplate, preventing a perfect conciseness score, but the overall length is reasonable and well-organized.

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 GET lookup, the definition is largely complete: all parameters are well documented in the schema, annotations cover safety, and the description explains the key wallet_type behavior. It could be slightly more complete by describing the response shape or explicitly routing agents to getPass when they have a pass ID, but those are minor gaps.

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

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

The input schema already provides 100% description coverage, including serial_number uniqueness, wallet_type enum/default, and x_app_id override semantics. The description mostly restates the wallet_type default rather than adding new parameter meaning beyond the schema, 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 opens with a specific verb and resource: 'Get a pass by serial number', then elaborates with 'Returns the full details of a single pass looked up by serial number.' This clearly differentiates the tool from sibling pass-lookup tools by identifying the exact lookup mechanism, and the OpenAPI mapping reinforces the unique endpoint.

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 clear context: this tool is for retrieving a pass when a serial number is known, and it explains how to handle the Apple/Google wallet ambiguity via `?wallet_type=`. It does not explicitly name sibling alternatives like getPass or state when not to use this tool, so it misses the highest bar for alternatives 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?

Adds meaningful behavior beyond the annotations: explicitly public, no authentication, maps to GET /share-pass/{token}, and shares the same API, billing, and rate limits. The warning not to invent other paths is an extra guardrail. No contradiction with readOnly/idempotent hints.

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?

Front-loaded with the core purpose, then adds auth context, endpoint mapping, and a rate-limit note. Slightly redundant with the tool name and operationId, but every sentence contributes useful information and the length is appropriate.

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, one-parameter public metadata lookup, the description covers purpose, authentication, endpoint, and constraints. Nothing needed to invoke the tool correctly is missing.

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

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

The only parameter, token, is fully described in the schema as 'Share token (32 hex characters),' giving 100% coverage. The description does not add further parameter-level details, so the baseline of 3 applies.

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

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

Clearly states the action ('Get shared pass metadata') and the resource (a shared pass), and specifies it returns public metadata with no authentication. The public-share-page use case and endpoint mapping further distinguish it from authenticated pass tools like getPass or downloadSharedPass.

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

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

Provides clear context: used by the public share page, no API key required, and maps to a specific public endpoint. It does not explicitly list sibling alternatives or exclusion conditions, but the intended use is easy to infer.

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, idempotentHint, and non-destructive behavior. The description adds useful context: requires templates:manage scope, maps to a GET endpoint, and shares PassFast billing/rate limits. There is 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 definition is compact and front-loaded with purpose. There is minor redundancy between 'Get a template' and 'Returns the full details...', but no material waste.

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

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

For a simple read operation, the schema, annotations, and description together cover scope, endpoint, idempotency, and return intent. No output schema exists, but 'full details' adequately conveys the result shape; error behavior is not specified.

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

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

Schema description coverage is 100%, and both id and x_app_id are already explained. The description's only param contribution is showing id as the path segment via /manage-templates/{id}; 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?

States a specific verb and resource ('Get a template', 'full details of a single template'), and the GET /manage-templates/{id} mapping makes the operation unambiguous. The 'single template' wording distinguishes it from listTemplates without needing the schema.

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 when/when-not guidance or named alternative tools, so an agent must infer from 'single template' that this is for fetching one template by ID. The scope and API-path notes are operational context, not selection guidance. This is adequate but not explicit.

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 define readOnlyHint, idempotentHint, and destructiveHint, so the description need not repeat them. It adds value by specifying the required organization scope and warning against inventing paths. This goes beyond annotation coverage and gives operational 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 compact, with a clear lead sentence, a bullet for scope, and a brief note on API mapping and constraints. Every line earns its place without fluff.

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

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

For a zero-parameter, read-only list operation, the description includes necessary operational context: scope, endpoint mapping (GET /manage-keys), and cautions about rate limits and path invention. Nothing essential is missing for an agent to call it correctly.

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

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

The tool has zero parameters, and per rubric the baseline is 4. The description correctly avoids speculative parameter details. No additional semantics are 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 action (List) and resource (API keys) with explicit scope ('current organization'). It is distinct from sibling tools like createApiKey, deleteApiKey, and revokeApiKey, making it 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 defines when to use the tool (to list all API keys for the organization) and adds a required permission scope (`org:manage`). It doesn't explicitly contrast with sibling list operations like listCertificates or listImages, but the resource type is obvious. The technical mapping and rate-limit note provide additional context.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable information beyond that: the required OAuth scope (certs:manage), the exact API path (GET /manage-certs), and a warning not to invent other paths. It also notes shared API, billing, and rate limits, giving the agent operational context without waiting for errors.

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 compact (four sentences) and front-loads the core purpose. The opening 'List certificates' is slightly redundant with the tool name, but the subsequent details (scope, path, rate limits) are useful. It avoids unnecessary fluff and stays efficient.

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

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

For a simple read-only list operation with one optional parameter, the description covers the essential call context: scope, endpoint, and operational constraints. It does not describe the return format or pagination, but with no output schema and a straightforward 'list' semantics, the implications are clear. Given annotations already handle safety, this is adequately 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 single parameter x_app_id is fully described in the input schema (100% coverage), including when to use it ('set it only for multi-app orgs'). The description does not mention parameters at all, so it adds no extra meaning beyond the schema. Baseline 3 applies because schema coverage is high.

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

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

The description clearly states the tool lists certificates for the current app, with a specific verb and resource. It also provides the OpenAPI operationId and GET path, making the purpose unambiguous. However, it does not explicitly contrast with sibling list tools (e.g., listApiKeys), so it stops short of full differentiation.

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

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

The description implies use when needing all certificates for the current app ('Returns all certificates for the current app'), and adds a scope requirement ('Scope: certs:manage'). It does not explicitly state when not to use it or name alternatives, so usage guidance is implied rather than explicit.

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 useful behavioral context beyond that: only active credentials are returned, the scope is the current app, and the operation maps to GET /manage-certs/google. It also warns against inventing other paths, which is a practical behavioral constraint.

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

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

The description is compact and front-loaded. The title line is followed by a one-sentence behavioral summary, then the scope and endpoint mapping, and a final constraint. Every sentence adds relevant information without noticeable 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 read-only listing operation with one optional parameter and no output schema, the description is complete: it states what is returned, the scope, the endpoint, the required service scope, and the API/rate-limit context. Nothing essential is missing for an agent to invoke it 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 description coverage is 100%, and the only parameter, x_app_id, already has a clear description in the schema. The tool description does not add any parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate because the schema carries the full burden.

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

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

The description uses the specific verb 'List' with the resource 'Google credentials' and then clarifies behavior: 'Returns all active Google Wallet credentials for the current app.' This clearly distinguishes it from sibling tools like listCertificates or testGoogleConnection. The OpenAPI operationId and path mapping further remove ambiguity.

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

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

The description gives clear context: it returns active Google Wallet credentials scoped to the current app, and it explicitly says 'Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.' It does not explicitly name alternatives or exclusions, so the usage guidance is clear but not fully comprehensive.

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, non-destructive behavior, and the description adds useful context: the required scope (`images:manage`), exact endpoint mapping, signed preview URLs, billing/rate-limit behavior, and a warning not to invent other paths. This goes beyond what annotations alone provide.

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

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

The description is compact and front-loaded with the core behavior, then uses bold labels for scope and endpoint details. Each sentence carries operational value, particularly the rate-limit note and the 'do not invent other paths' warning.

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 list operation with one optional parameter and no output schema, the description is sufficient: it clearly states scope, output content, endpoint, and API policy. Nothing critical is missing for an agent to invoke it correctly.

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

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

The only parameter, x_app_id, is fully documented in the schema with 100% coverage, including guidance for multi-app orgs. The description does not add additional parameter-specific semantics, so the 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 states a specific action ('List images') and clarifies scope ('all images for the current app') plus a distinct output feature ('signed preview URLs'). This differentiates it from image mutation/usage siblings such as uploadImage, deleteImage, and getImageUsage.

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 the tool—when you need all images for the current app—but it never explicitly states when to prefer this over related image tools or when not to use it. It provides operational constraints such as the same API/billing/rate limits, but no explicit alternative or exclusion 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: pagination, scope requirement, and that it maps to a specific HTTP endpoint with shared rate limits. It doesn't describe the response shape, but with no output schema and read-only semantics, the added context is meaningful.

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 compact and front-loaded: the core action is in the first line, followed by scope, endpoint mapping, and a guardrail. Every sentence earns its place, and the formatting is clean and scannable.

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 10 optional parameters and full schema coverage, the description is nearly complete. It covers scope, endpoint, pagination, and rate limits. The only minor gap is not describing the response format or default ordering, but since there is no output schema and the tool is a simple list, this is acceptable.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters. The description adds no parameter-specific meaning beyond what the schema provides, but it does mention pagination generally. Baseline 3 is appropriate because the schema carries the full burden and the description doesn't need to compensate.

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

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

The description states a specific verb and resource ('List passes') and clarifies it returns a paginated list for the current app. It also maps to the OpenAPI operationId and endpoint, which helps disambiguate from siblings like getPass, getPassBySerial, and listTemplates. However, it doesn't explicitly contrast with sibling list tools, so it's clear but not fully differentiated.

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: it lists passes for the current app, requires the `passes:read` scope, and notes the same HTTP API, billing, and rate limits. It also warns not to invent other paths. It doesn't explicitly say when to use this over getPass or listTemplates, but the scope and endpoint mapping give enough context for an agent to select it appropriately.

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, idempotentHint, and destructiveHint. The description adds valuable context: the exact HTTP path (GET /manage-templates), the scope requirement, and the note about identical billing/rate limits. This goes beyond the annotations without contradicting 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?

The description is concise and well-structured, front-loading the core action and then providing essential scope and API mapping details. It avoids redundancy, though a couple of phrases (e.g., 'Same PassFast HTTP API') could be trimmed, but overall it is efficient.

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

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

For a simple list tool with no required parameters and no output schema, the description covers the essential context: scope, path, default behavior, and rate-limit note. An agent has enough information to invoke it correctly without additional clarification.

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 schema descriptions fully explain both parameters. The description repeats the archived behavior but adds no new semantic detail beyond the schema. Since the schema carries the burden, 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 clearly states the verb 'List' and the resource 'templates', and specifies the scope ('current app'). It distinguishes from siblings by explaining the default vs. archived filter and mentions the OpenAPI operationId and path, which differentiates it from getTemplate and other list tools.

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

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

The description explains the default behavior and how to get archived templates via the archived parameter. It also mentions the required scope ('templates:manage'). While it does not explicitly name alternatives, the distinction from getTemplate is implied and the purpose clarity covers the main usage context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds value by mentioning pagination, the required scope 'org:read', mapping to a GET endpoint, and noting that the same API, billing, and rate limits apply. This extra context about the API behavior is useful beyond what annotations provide.

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

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

The description is concise and well-structured. The main purpose is stated in the first line, followed by a scope note and an API mapping. It contains no filler and every sentence earns its place. The formatting with bolded scope improves 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?

For a read-only listing tool with rich annotations and a fully described schema, the description is sufficient. It provides scope, API mapping, and rate-limit context. Since there is no output schema, the description could have mentioned the return structure, but the pagination hint implies a list. Overall, it covers all essential information an agent needs to call it correctly.

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

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

The input schema has 100% description coverage, so every parameter is already documented. The description does not add new semantics; it mentions pagination, but limit/offset are already explained in the schema. Since the schema carries the load, 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 clearly states the verb 'List' and the resource 'webhook events', and further specifies 'webhook event delivery records for the current app'. This precisely defines the tool's scope and differentiates it from other list tools like listPasses or listTemplates, which are for different resources. It is not a tautology and gives the agent a clear understanding of what to expect.

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: it is for listing webhook event delivery records for the current app. It does not explicitly name alternatives or state when not to use it, but the scope ('for the current app') and the note 'Do not invent other paths' implicitly guide usage. There are no explicit exclusions, but the context is sufficient for an agent to decide when to call this tool.

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

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

Adds valuable context beyond annotations: published templates become immutable, the action requires the 'templates:manage' scope, and it shares the same API/billing/rate limits. Annotations already cover readOnly/destructive/idempotent hints, and the description supplements them without 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 well-structured, front-loaded with the primary purpose, and uses bold headers for scope and API mapping. Every sentence earns its place, including the guard against inventing other paths, and it is appropriately sized.

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, preconditions (draft), post-condition (immutability), scope, and API mapping. The main gap is lack of response format details, but with no output schema and full parameter coverage, this is a minor omission.

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

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

Schema coverage is 100% with descriptions for both id and x_app_id. The description references the POST path containing {id} but adds no new meaning beyond what the schema already provides, 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 it publishes a draft template to make it available for pass generation, using a specific verb ('publish') and resource ('template'). It distinguishes itself from siblings like create, update, and delete by describing the lifecycle stage and the irreversibility after publishing.

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

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

Provides clear context: use when a draft template is ready for publication, and notes published templates cannot be modified, implying edits must occur beforehand. However, it does not explicitly name alternative tools (e.g., updateTemplate) or state when not to use it, so it lacks explicit exclusions.

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

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

Annotations already indicate a destructive, non-read-only operation; the description adds meaningful behavioral context: revoked keys become inactive, cannot authenticate, require scope org:manage, map to PATCH /manage-keys/{id}, and must not be called via invented paths.

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 content is useful and front-loaded, but 'Revoke an API key' is immediately restated by 'Revokes an API key'. The endpoint and scope details earn their place, though the redundancy weakens the structure.

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 one-parameter destructive operation, the description covers the effect, scope, API mapping, and a guard against hallucinated paths. It is nearly complete, though it does not mention the expected response or whether revocation is reversible.

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 fully documents the single required id parameter as a UUID API key ID, so the description does not need to repeat it. The description adds no extra parameter-level meaning, but 100% schema coverage makes this acceptable.

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

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

The description states a specific action and resource: revoke an API key, making it inactive and unable to authenticate. This clearly distinguishes the operation from deletion or creation, and the state transition is explicit.

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?

There is no guidance on when to revoke versus delete or manage an API key, and no prerequisites or exclusions are provided. The intended usage is only implied by the tool name and the first sentence.

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?

Goes well beyond the annotations by disclosing that the test pass is ephemeral, not stored, returns a binary download, requires certs:manage scope, and shares billing/rate limits. This gives the agent accurate behavioral expectations without relying on structured data.

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

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

The description is compact and front-loaded with the core purpose. The operationId/path mapping and 'Same PassFast HTTP API' line add some context but are slightly redundant; still, no sentence is wasted.

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 one optional parameter and no output schema, the description adequately covers return format, persistence behavior, and side-effect considerations. It could mention error/edge-case behavior, but that is not critical for basic invocation.

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

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

Input schema description coverage is 100% for the single optional x_app_id parameter, so the schema already explains it. The description adds no parameter-specific meaning, matching the baseline for high schema coverage.

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

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

Description states a specific action and resource: it tests Apple signing certificates by generating an ephemeral .pkpass file and returning it as a binary download. This clearly distinguishes it from sibling tools like testGoogleConnection or testWebhook.

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 makes the intended use clear: verify uploaded Apple signing certificates are valid and complete. It also gives scope and operation mapping, but it does not explicitly name alternatives or state when not to use this tool.

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

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

Beyond annotations, the description reveals the authorization scope (`certs:manage`), the exact HTTP endpoint, and that standard PassFast billing and rate limits apply. It also warns against inventing other paths. These are behavioral details not captured in annotations. It doesn't describe side effects or response, but the test nature plus destructiveness=false cover the main safety profile.

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

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

Four short sentences, front-loaded with the purpose. The scope, endpoint mapping, and constraint are each useful and non-redundant. No filler.

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

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

For a one-parameter test tool, the description is mostly complete, but the absence of an output schema is not compensated for: the agent is told nothing about the response format or how to interpret success/failure. Also, prerequisites such as previously uploaded credentials are only implied by 'configured.'

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 covers the only parameter (`x_app_id`) with a full description, so the schema does the heavy lifting. The tool description adds nothing about parameters, which is acceptable given 100% schema coverage.

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

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

States a specific verb ('tests') and resource ('configured Google Wallet credentials'), and clarifies exactly what the operation does (attempts to authenticate with the Google Wallet API). The endpoint and operationId further pin it down and distinguish it from sibling test tools like testAppleCertificates.

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 context is implied: this is the tool to call to verify Google Wallet credentials. However, it does not explicitly contrast with alternatives such as testAppleCertificates or testWebhook, nor does it state when not to use it. The 'Do not invent other paths' line is a constraint, not usage 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 indicate non-readOnly (readOnlyHint=false), openWorld (openWorldHint=true), and non-idempotent (idempotentHint=false). The description adds that it sends a sample webhook payload to an external URL and returns the result, which is consistent with openWorldHint and provides concrete behavioral detail. It also notes billing and rate-limit implications. This goes beyond the annotations without contradicting them, though it does not elaborate on the exact side effects (e.g., whether the webhook delivery is synchronous or asynchronous).

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

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

The description is concise and well-structured. It opens with the purpose, then explains the action, then adds scope and API mapping. Every sentence earns its place, and there is no fluff. It is front-loaded with the most important 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 tool with one optional parameter and no output schema, the description is largely complete. It explains the behavior, the API mapping, and the scope. The only minor gap is that it does not describe the shape of the result (beyond 'returns the result') or any prerequisites (e.g., that an app must be configured). Given the simplicity, this is acceptable.

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

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

The input schema covers 100% of the single parameter (x_app_id) with a clear description: 'Override X-App-Id for this call. Omit the connection header by default; set it only for multi-app orgs.' The tool description itself does not mention the parameter, so it adds no extra meaning. Given the high schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description states a specific verb ('Test'), a specific resource ('validation webhook'), and explains the action ('sends a sample validation webhook payload to the configured URL and returns the result'). This clearly distinguishes it from sibling tools like testAppleCertificates and testGoogleConnection, which test different integrations. The explicit reference to the OpenAPI operationId and path further removes ambiguity.

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

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

The description provides useful context: it specifies the scope ('org:manage'), maps to a specific HTTP endpoint, and notes 'Same PassFast HTTP API, billing, and rate limits. Do not invent other paths.' This implies when to use it (for testing the validation webhook) but does not explicitly name alternatives or state when not to use it. The guidance is clear enough but not exhaustive; a sentence naming the other test tools (e.g., testAppleCertificates) would have made it a 5.

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

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

The description discloses the special behavior of `regenerate_webhook_secret` (new secret returned only once in `webhook_secret_raw`), which is valuable beyond the schema. It also mentions scope (`org:manage`), same API/billing/rate limits, and the PATCH method. Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds context about the one-time secret display.

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 compact and front-loaded: it states the purpose in the first line, then adds the critical webhook secret behavior, scope, and endpoint mapping. Every sentence earns its place, and the warning about not inventing paths is a useful guardrail.

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 10-parameter update tool with no output schema, the description covers the key behavioral nuance (one-time secret), scope, and endpoint. It doesn't describe the full response shape, but the schema covers parameters and the description covers the critical return value. The lack of an output schema is partially mitigated by the description's mention of `webhook_secret_raw`.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters. The description adds meaning for `regenerate_webhook_secret` (explaining the one-time return of the secret) but doesn't need to explain the others since the schema covers them. Baseline 3 is appropriate.

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

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

The description clearly states the tool updates the current app's settings, including webhook configuration, and explicitly maps to the OpenAPI operationId `updateApp` with PATCH /manage-org/app. It distinguishes itself from sibling tools like updateOrganization and updateTemplate by naming the resource (app) and the endpoint.

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

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

The description provides clear context for when to use this tool (updating app settings) and explicitly warns not to invent other paths. It doesn't explicitly name alternatives like getApp for reading or createApp for creating, but the scope and endpoint mapping make the usage context clear.

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

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

Annotations already mark this idempotent and non-destructive; the description adds behavioral context beyond them by giving the HTTP PATCH path, required `org:manage` scope, and noting the same billing and rate limits apply. No contradiction with annotations.

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

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

The description is short, front-loads the core action, and adds only a few operationally relevant details. The 'do not invent other paths' line is slightly defensive but still earns its place against hallucinated endpoints.

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, optional-field PATCH with no output schema, the description covers scope, endpoint, and rate-limit expectations. It does not explain partial-update semantics when no fields are supplied, but that is a minor gap given the schema and annotations.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only adds that APNs-specific parameters are included, which is useful but not necessary 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 states a specific verb and resource: 'Updates the current organization's settings, including APNs credentials.' The target is clearly the organization, not apps, passes, or templates, which distinguishes it from the many update* siblings.

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

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

It gives clear context for when to use it: updating the current organization's settings, and it declares the required scope `org:manage`. It does not explicitly name sibling tools to avoid, but the org-scoped context is enough to route an agent correctly.

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=false, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral context: it can trigger push notifications, has scope passes:manage, maps to PATCH, and explains strip_image_id override behavior and rate-limit alignment. It also cautions against inventing paths, enhancing transparency well 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?

The description is well-structured and front-loaded with the core action, followed by scope and mapping details. It is slightly long but every sentence contributes value, and there is no redundant 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 complex update tool with 9 parameters and no output schema, the description covers key constraints, required-field rules, scope, and behavioral notes. It omits explicit return-value details, but for an update operation this is not critical, and the description is sufficiently complete for correct invocation.

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

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

Schema coverage is 100% with descriptions for all parameters, so the baseline is 3. The description adds the 'at least one of' constraint (not present in the schema) and clarifies the push_update flag's effect, providing meaningful semantic value 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 states a clear verb and resource ('Update a pass') and specifies the scope ('dynamic data of an active pass'), mapping to the OpenAPI operation. It is unambiguous, though it does not explicitly contrast with the sibling updatePassBySerial, so it loses a point for not differentiating by name.

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

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

The description provides useful context: it targets active passes, requires at least one of several fields, and mentions optional push notifications. However, it offers no explicit guidance on when to prefer this tool over updatePassBySerial or when to avoid it, leaving usage conditions 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?

Beyond the annotations, the description discloses the side effect of optionally sending push notifications, the active-pass prerequisite, the required scope (passes:manage), and the shared HTTP API/billing/rate-limit behavior, plus a directive not to invent other paths. This is substantial contextual information the structured annotations do not provide.

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

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

The key summary sentence is front-loaded, followed by compact, high-value constraints, scope, and API mapping. Every sentence earns its place and no filler is present.

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 10-parameter mutation with nested objects and no output schema, the description covers preconditions, required-field constraints, auth scope, and API context. The main gap is that it does not describe the response/return value or error behavior for non-existent/inactive serials, which an agent would need when handling results.

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

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

Input schema already documents all 10 parameters, so the baseline is 3. The description adds real value by stating the cross-parameter 'at least one of...' requirement and clarifying how wallet_type resolves dual-wallet serials; it does not, however, compensate for details like strip_image_id's relationship to that requirement.

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?

First sentence uses a specific verb and resource: 'Update a pass by serial number', and adds the lookup key and active-pass constraint. This clearly distinguishes it from sibling updatePass and serial-based read/void tools without needing to open the schema.

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 concrete invocation conditions: only active passes, at least one of data/expires_at/locations/relevant_date/max_distance must be supplied, and wallet_type must be chosen when both Apple and Google passes share a serial. It does not explicitly name the alternative update tool (updatePass) or say when not to use it, so it falls short of a 5.

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

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

Annotations already cover the read-only/destructive/idempotence profile, and the description adds behavioral context beyond them: the draft-only constraint, required scope `templates:manage`, and a definitive endpoint mapping. It does not describe the outcome of attempting to modify a published template, but this 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?

Five short lines, front-loaded with the purpose and key constraint. The endpoint, scope, and rate-limit lines are useful guardrails, and there is 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?

This is a 16-parameter tool with a deeply nested `structure` object and no output schema, yet the description does not state what the call returns, how errors for published templates are surfaced, or which top-level fields are updatable. The draft-only constraint and scope are helpful, but they do not make the definition complete for such a complex 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 description coverage is only 31%, so the description needed to compensate, but it only mentions the id via the PATCH path. It gives no guidance on `structure`, `pass_style`, `wallet_types`, image IDs, or partial-update semantics beyond the PATCH verb.

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

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

States a clear action ('Update a template') and immediately narrows it with 'Updates a draft template. Published templates cannot be modified.' This distinguishes it from createTemplate, publishTemplate, and deleteTemplate, giving the agent a concrete resource and scope.

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

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

The description tells the agent this tool is for draft templates and that published templates are off-limits, which is a clear when-not condition. It does not explicitly name alternatives such as publishTemplate for published templates, so it stops short of a 5.

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

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

Annotations already signal a write operation (readOnlyHint:false, idempotentHint:false). The description adds useful context by declaring the required auth scope, the exact endpoint, and warning against inventing alternate paths. There is no contradiction with 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 compact and front-loaded, with each sentence earning its place: format, scope, endpoint, and API constraints. The warning 'Do not invent other paths' is concise and actionable.

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 three-parameter upload with full schema coverage, the description supplies the necessary API identity, auth scope, and endpoint. It does not describe response or error behavior, but with no output schema and a straightforward upload this is a minor gap; the main missing piece is explicit sibling differentiation.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description only reinforces the certificate/key concept and does not add new meaning about cert_type, cert_data, or x_app_id beyond what the schema 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 opens with a direct statement: 'Uploads a single PEM-encoded certificate or key.' This gives a specific verb and resource, and the PEM format distinguishes it from the sibling uploadP12Certificate. Mapping to POST /manage-certs further anchors the 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?

It provides operational context such as scope certs:manage, the exact OpenAPI operation, and the note about the same API/rate limits. However, it never explicitly states when to use this tool over uploadP12Certificate or other upload tools, so the usage guidance is clear but lacks explicit alternatives or exclusions.

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

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

Annotations already mark this as non-readonly and non-idempotent. The description adds useful context by stating that the service account JSON and issuer ID are stored securely, that the operation requires certs:manage scope, and that it follows the same PassFast API billing and rate limits. This goes beyond the structured annotations without contradicting 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?

The description is compact and front-loaded with the core action and purpose. Additional lines provide scope, endpoint mapping, and API behavior without filler. Every sentence 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 three-parameter mutation with no output schema, the description covers the essential facts: what is uploaded, why it is stored, the required scope, and the API contract. It does not explain the response format or duplicate-upload behavior, but the annotations and schema already address side-effect expectations reasonably well.

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 every parameter is already documented with type and meaning. The description mentions the two required values in prose but does not add any detail beyond what the schema provides. This meets the baseline but does not elevate 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 identifies a specific verb and resource: it uploads Google service account credentials for Google Wallet pass signing. It also names the endpoint and scope, which helps distinguish it from sibling upload tools like uploadCertificate and uploadP12Certificate. No ambiguity remains about what this 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 does not tell an agent when to choose this tool over related siblings such as testGoogleConnection, listGoogleCredentials, deactivateGoogleCredential, or uploadCertificate/uploadP12Certificate. It provides scope and API context but no explicit when/when-not or alternative guidance. Selection must be inferred from the name and general purpose.

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 thoroughly discloses that non-strip uploads replace and delete previous images from storage and DB, while strip uploads accumulate. This directly contradicts the annotation destructiveHint=false, which signals a non-destructive operation. Because the description contradicts an annotation, the score is capped at 1 per the rubric.

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

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

The description is appropriately detailed for a complex tool, with bolded purpose categories and bullets. Every sentence earns its place, explaining behavior, lifecycle, scope, and endpoint mapping without excessive filler. The only trivial redundancy is the title-like first line 'Upload an image.'

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

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

Despite no output schema, the description covers endpoint mapping, required multipart fields, purpose-specific behavior, deletion side effects, scope (images:manage), billing/rate limits, and the returned id for strip usage. An agent has enough context to invoke the tool correctly and interpret the result.

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 purpose, file_base64, filename, and x_app_id. The description mostly restates the schema's purpose semantics (strip accumulates, others replace) and adds only minor reinforcement about multipart encoding. This meets the baseline but does not materially expand on 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 names the resource (image), its use cases (pass templates or per-pass strip overrides), and maps to a concrete endpoint/operationId (POST /manage-images, uploadImage). It clearly differentiates from sibling upload* tools like uploadCertificate and uploadGoogleCredentials by specifying images and their purposes.

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

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

It explicitly states when to use the tool: for pass template assets or per-pass strip overrides, and gives detailed purpose-by-purpose behavior. It does not explicitly list exclusions such as 'do not use for certificates or credentials,' but the image scope and operation mapping make the boundary 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 cover readOnly, idempotent, and destructive hints (false for all). The description adds meaningful behavioral details: the bundle is decrypted with the provided password, certificates are extracted, and stored with AES-256-GCM encryption. It also specifies the required scope. This goes beyond annotations without contradicting 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?

The description is efficiently structured with a clear one-line summary followed by brief explanatory details. Each sentence carries value: purpose, process, scope, mapping, and a caution. It is front-loaded and contains 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?

The description covers the main functional aspects, scope, and OpenAPI mapping. However, it lacks any mention of return values or error scenarios (no output schema exists), and it does not clarify whether uploading replaces an existing certificate or handles duplicate situations. Given the possibility of similar siblings (uploadCertificate), this is a noticeable gap but not critical.

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 the password in the process but does not add any new meaning beyond what the schema already provides for each parameter. No additional context about parameter usage, formats, or constraints 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?

The description clearly states the action (upload a .p12 certificate bundle) and the resource (signer certificate and private key). It explains the process of decryption and encrypted storage. It does not explicitly differentiate from the sibling uploadCertificate, but the .p12 format makes the purpose specific enough.

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 .p12 bundles and warns against inventing other paths ('Do not invent other paths'), but it does not explicitly state when to choose this over alternatives like uploadCertificate or mention any prerequisites or conditions. Usage context 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 indicate destructiveHint=true, but the description adds valuable behavioral detail: it explains the push notification side effect, the non-fatal rebuild failure (pass is still invalidated at DB level), and the scope. These details go beyond the annotations and give the agent a clear picture of consequences.

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

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

The description is concise and well-structured: a clear heading, two sentences on effect, a bullet for scope and API mapping, and a final warning. Every sentence adds value, and the most important information (voiding effect) is front-loaded.

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

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

For a destructive mutation with no output schema, the description covers the essential aspects: what happens (invalidation, rebuild), side effects (push notifications), failure tolerance (non-fatal), and API binding. It could mention the response format, but since there is no output schema, this is not a critical gap. Overall, it is complete 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?

The schema already provides 100% coverage with descriptions for both id and x_app_id. The description does not add parameter-specific details, which is acceptable given the high schema coverage. It mentions the API path and scope but not parameter semantics, so it stays at the baseline.

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

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

The description opens with 'Void a pass' and immediately clarifies the exact resource and action: marks a pass as invalidated and rebuilds the .pkpass with Apple's voided: true flag. It clearly distinguishes from sibling voidPassBySerial by focusing on the pass ID and the API path, so an agent can differentiate without opening the schema.

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

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

The description provides explicit usage context: it states the required scope (passes:manage), maps to the exact OpenAPI operation and endpoint (POST /manage-passes/{id}/void), and warns not to invent other paths. It does not explicitly compare with alternatives like voidPassBySerial, but the context is sufficient for an agent to understand when to call this tool.

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

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

The description discloses the full behavioral impact: marks pass invalidated, rebuilds .pkpass with Apple's voided flag, and sends push notifications. It also states the required scope (passes:manage) and API path, adding substantial context beyond the destructiveHint annotation. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core action. Each sentence adds information about effects, scope, API mapping, or constraints. It is slightly verbose but not redundant, and the logical flow aids comprehension.

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

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

The description covers the action's outcome, scope, API path, and constraints (e.g., 'do not invent other paths'). It lacks explicit error-case handling, but for a destructive mutation with annotations indicating non-idempotence, this is sufficient for an agent to call it correctly.

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

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

The input schema already provides detailed descriptions for all three parameters (100% coverage). The description adds a note about wallet_type default and purpose, but that is already present in the schema. It does not provide significant additional semantic value beyond what the schema offers.

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 verb (void) and resource (pass by serial number), and explains the effect (marks invalidated, rebuilds .pkpass with voided flag). It also distinguishes this tool from siblings like voidPass by specifying serial-number lookup, and clarifies the wallet_type selection for dual-wallet serials.

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 explicit guidance on when to use the wallet_type parameter (when a serial has both Apple and Google passes) and notes the default behavior. It provides scope and API mapping, but does not explicitly mention alternative tools like voidPass for ID-based voiding, leaving some usage context implicit.

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