Goodeye

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

With no annotations providing behavioral hints, the description fully discloses the effects: creating a member row for team_membership or transferring ownership for ownership invitations, and returning the result payload. This exceeds the typical burden for transparency.

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

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

The description is concise, with three sentences that front-load the main action and efficiently cover preconditions, behavioral details, and return value. No unnecessary words or redundancy.

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

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

Given the tool's simplicity (one parameter, output schema exists), the description covers purpose, preconditions, effects, and return. It lacks info on error cases or permissions but is largely complete, warranting a score of 4.

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

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

The input schema covers the single parameter with 100% description, including its purpose as a UUID. The description adds no additional semantic value beyond what the schema already provides, so the baseline score of 3 is correct.

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 accepts a pending invitation, specifying the two types of invitations (team_membership and ownership) and their outcomes. While the purpose is distinct from siblings like cancel_invitation or decline_invitation, it does not explicitly differentiate itself, so a score of 4 is appropriate.

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 usage: the invitation must be pending and not expired. However, it does not mention when to use alternatives (e.g., decline_invitation), which prevents a higher score. It achieves a 4 for clear usage context without 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 write operation (readOnlyHint=false). The description adds value by specifying the 'Owner only' constraint, which is critical for correct invocation. It does not detail potential side effects like duplicate handling, but the owner requirement is a meaningful behavioral disclosure.

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

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

Two concise sentences, front-loaded with the core action. Every sentence provides distinct information: the action, the owner constraint, and identifier formats. No filler or redundancy.

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

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

While the output schema is present (covering return values), the description lacks important context such as error conditions (e.g., if user already a team member), relationship to invitation flow, or required user existence. For a simple tool, this is adequate but not comprehensive.

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 already describes both parameters well. The description only reiterates that user_identifier accepts UUID, email, or handle, which is already in the schema. No additional meaning is added 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?

Description clearly states the verb 'Add' and resource 'user to a team', making the action unambiguous. It also specifies the owner-only restriction and accepted identifier formats, differentiating it from sibling tools like remove_team_member and list_team_members.

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

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

The description implies usage context ('Owner only') but does not explicitly state when to use versus alternatives like invitations or other team management tools. No mention of prerequisites like user existence or team membership status.

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 idempotentHint=true, destructiveHint=false. The description adds valuable context: it sets 'archived_at' and keeps the slug occupied. No contradictions.

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

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

Two sentences, front-loaded with action and idempotency, no wasted words. Perfectly concise.

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 only one required parameter and an output schema present, the description covers ownership, idempotency, and behavioral details adequately. No gaps.

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

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

Input schema has 100% coverage with a clear description for skill_id. The description does not add further parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the action 'Archive' and the resource 'skill you own', and distinguishes it from siblings like 'delete_skill' by noting it sets 'archived_at' and keeps the slug occupied. The ownership condition 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?

The description indicates usage on owned skills and mentions idempotency, providing clear context. However, it does not explicitly state when not to use or mention alternatives like 'unarchive_skill'.

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 idempotentHint=true and destructiveHint=false. The description adds rich behavioral context: owner-only access, slug occupation, hiding from public listing, fork persistence, metadata update on lineage, and idempotency for already-archived templates. No contradictions 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 concise, with four focused sentences. It front-loads the main action and identifier format, then lists key behavioral effects and conditions. No wasted words.

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

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

Given the simple parameter set (2 params) and existence of an output schema, the description covers the main action, ownership, idempotency, effects on slugs and forks, and visibility. It sufficiently explains the tool's behavior 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%, so baseline is 3. The description does not add new meaning beyond what the schema provides for 'template_id' (UUID or @handle/slug) and 'archive_reason' (optional note). It mentions 'Owner only' but that's not tied to a specific parameter.

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

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

The description clearly states the tool archives a template by UUID or @handle/slug. It distinguishes from siblings like 'delete_template' (archiving keeps slug occupied and hides from public, but forks keep working) and 'unarchive_template' (reverse action). The verb 'Archive' and resource 'template' are specific.

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 specifies 'Owner only' as a usage constraint, and explains effects (slug occupied, hidden from public, forks continue). It implicitly contrasts with deletion and unarchiving, but does not explicitly name alternatives like 'delete_template' or 'unarchive_template'. This is clear but lacks explicit exclusionary guidance.

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

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

The description states it applies fixes via save_skill, which is a write operation, but annotations declare readOnlyHint=true. This direct contradiction severely misleads the agent about the tool's side effects.

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

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

The description is thorough and front-loaded with the core purpose, but slightly verbose in detailing the audit process. Every sentence is informative, but some redundancy exists.

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

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

Given the complexity and presence of an output schema, the description provides a complete picture of inputs, process, and outputs. However, the contradiction with annotations undermines trust and completeness.

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

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

With 100% schema coverage, the description adds significant value by explaining the two modes, the optional nature of skill_id, and the interactive local file audit, far exceeding the schema's brief 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 clearly states the tool reviews a skill against best practices and fixes flags, with specific verbs 'Review' and 'fix'. It distinguishes between auditing a hosted skill (via skill_id) and a local file, differentiating it from sibling tools like get_skill or save_skill.

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 two usage modes (with or without skill_id) and implies when to use each. It references related tools (run_verifier, save_skill) but does not explicitly list when not to use or compare to alternatives like optimize_skill.

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 state change (resolution='cancelled') and the effect on the recipient, beyond what annotations provide. It confirms the mutation (readOnlyHint=false) and non-destructive (destructiveHint=false) nature, with idempotency implied but not elaborated. 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 extremely concise with three short sentences, each adding crucial information: purpose, effect, and return value. No redundant words.

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

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

Given the simple tool with one parameter and an output schema, the description is mostly complete. It covers purpose, constraint, outcome, and return format. However, it could mention error scenarios (e.g., if not proposer or invitation already processed).

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 does not add significant meaning beyond the schema's description of invitation_id as a UUID, but it confirms the parameter's role in the cancellation action.

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 'cancel' and the resource 'pending invitation you sent', with a scope constraint 'proposer only'. It effectively distinguishes this tool from its siblings like accept_invitation and decline_invitation.

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 specifies the user must be the proposer and explains the effect (recipient cannot accept/decline). However, it does not explicitly state when not to use it or mention alternative tools, though the sibling context provides some guidance.

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

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

The description adds context beyond the annotations by specifying that cancellation occurs at the end of the billing period, not immediately. This aligns with the non-destructive hint and idempotent hint, providing useful behavioral transparency.

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

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

The description is a single sentence with no wasted words, clearly communicating the action and timing. It is appropriately concise and front-loaded.

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

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

Given no parameters and the existence of an output schema, the description explains the core action and timing. It could mention the post-cancellation state (e.g., downgrade to free), but overall it is fairly complete for a simple 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?

There are no parameters, and schema coverage is 100%, so the description does not need to add parameter information. The baseline for no parameters is 4.

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

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

The description clearly states the tool cancels a Pro subscription at the end of the current billing period, which is a specific verb+resource combination and distinguishes it from siblings like upgrade_to_pro and create_billing_portal_session.

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

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

The description implies the tool should be used when the user wants to cancel their Pro subscription at period end, but it does not explicitly state when not to use it or provide alternative tools for other cancellation scenarios (e.g., immediate cancellation).

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 value beyond annotations by disclosing billing ('Bills two metered verifier runs') and enumerating possible statuses ('clean', 'flagged', 'blocked', or 'error') with per-side details. 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 concise (~80 words) and well-structured: first sentence states purpose, then details resolution, visibility, billing, and output. No extraneous 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 safety check tool, the description covers input resolution, visibility rules, billing impact, and output format (status with per-verifier details). Completeness is adequate given output schema exists.

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

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

With 100% schema coverage, description adds context: explains 'skill_id' resolution (UUID/slug) and that 'version' defaults to latest. This provides meaning 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 starts with a specific verb+resource+scope: 'Run both system safety verifiers against a saved skill version.' It clearly distinguishes from siblings like 'run_verifier' by specifying it runs two system verifiers, not a single one.

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 context on resolution (UUID/slug) and visibility (owner or grant), and mentions defaulting to latest version. However, it does not explicitly state when NOT to use this tool or compare to alternatives like 'run_verifier'.

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 (readOnlyHint=false, destructiveHint=false) indicate it's not read-only or destructive. The description adds that it 'Bills two metered verifier runs against the caller', disclosing a cost implication not captured in annotations. It also describes the output structure 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 two paragraphs, concise and front-loaded with the main purpose. It includes necessary details without being verbose. Could be slightly more structured, but overall efficient.

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

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

Given the complexity (two verifiers, billing, multiple ID formats, output fields) and presence of an output schema, the description adequately covers the tool's behavior and effects. It mentions billing and status outcomes, which is sufficient for the agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining that template_id can be a UUID, slug, or @handle/slug, and reinforces the version parameter's behavior. This goes beyond the schema descriptions.

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

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

The description clearly states the tool runs both system safety verifiers on a published template version. It specifies the verb 'run', the resource 'template version', and the scope 'both system safety verifiers'. This distinguishes it from siblings like 'check_workflow_safety' and 'run_verifier'.

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 how to specify the template (UUID, slug, @handle/slug) and defaults to the latest live version. It mentions billing and different access patterns (REST vs MCP). While it doesn't explicitly state when not to use, it provides sufficient context for usage.

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

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

Beyond annotations (idempotentHint=true, etc.), the description adds validation against reserved list, collision rejection, and field stamping. It also clarifies idempotency behavior for re-submission, providing useful 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?

Description is three concise sentences with purpose first, then behavior, then idempotency. Every sentence adds value; no unnecessary words.

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

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

For a simple one-parameter tool with an output schema, the description covers purpose, validation, idempotency, and effects. Given the annotations and schema details, it feels complete.

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

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

Schema covers 100% with a clear description for the handle parameter. The description adds that handle is validated against a reserved list, but does not add significant new meaning 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?

Description clearly states 'Claim a handle for the authenticated caller', specifying the verb, resource, and actor. This distinguishes it from sibling tools like rename_handle or accept_invitation.

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 first-time handle claiming but lacks explicit guidance on when not to use it or mention of alternatives like rename_handle. Contextual information 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?

The description adds behavioral context beyond annotations, such as error behavior ('Errors clearly when no default payment method is on file, or when the requested amount... falls outside the allowed range') and the fact that re-running clears previous failed state. Annotations are all false and are consistent.

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 at three sentences, with the main action front-loaded. Every sentence adds value (prerequisite, error handling, retry behavior) 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?

Given the tool's complexity (3 parameters with defaults, prerequisite, error cases) and the presence of an output schema, the description is complete. It covers necessary context for the agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the parameter types (amount, threshold, monthly cap) but does not add new meaning beyond what the schema provides.

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

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

The description clearly states the main action: 'Turn on automatic credit top-ups and set (or update) their terms.' It uses a specific verb ('turn on and set/update') and resource ('automatic credit top-ups'), and distinguishes from siblings like disable_auto_top_up and purchase_credits.

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

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

The description provides usage guidance by stating a prerequisite: 'Requires a default payment method already on file (a manual credit purchase saves one).' It also explains that re-running clears failed state, acting as a retry. While it doesn't explicitly say when not to use it, the context of sibling tools implies its 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 does not disclose any behavioral traits beyond the annotations. It mentions 'get a link' but does not specify whether it creates a session (write) or just retrieves a URL. Annotations have readOnlyHint=false, which is not contradicted, but no extra context on auth, rate limits, or side effects.

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

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

Single sentence that is clear and to the point. No wasted words.

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

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

For a tool with no parameters and a simple purpose, the description is sufficiently complete. It explains what the tool does and what it returns (a link). Output schema is available for return type 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?

No parameters exist, and the input schema is empty with 100% coverage. The description does not need to add parameter info; baseline of 4 is appropriate.

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

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

The description clearly states the tool 'gets a link' to the 'Stripe billing portal' for managing subscription and payment. It is specific and distinguishes from siblings like cancel_subscription.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools include cancel_subscription and upgrade_to_pro, but the description does not clarify when to choose this one.

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

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

Discloses handle immutability and namespace sharing, and failure condition. However, with no behavioral hints in annotations (all false), description could elaborate more on side effects or permissions required. It adds some value beyond annotations but is not exhaustive.

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

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

Two concise sentences that front-load the primary action and add key constraints. No wasted words.

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

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

For a single-parameter creation tool with an output schema, the description covers the essential failure condition and handle behavior. It feels complete for the tool's complexity, though it could briefly mention what the response contains (but output schema likely covers that).

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 a detailed description of the handle parameter. The description repeats the immutability and namespace info already present in the schema, adding no new semantic information, so 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 it creates a team owned by the caller, with specific verb and resource. It is unambiguous and distinct from sibling tools like delete_team or list_teams.

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 failure condition (handle_not_claimed if provisional handle held) and notes handle namespace sharing, offering context for when to use. Lacks explicit alternatives but given uniqueness of the tool, guidance is clear.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds detail: sets resolution='declined', mentions idempotency with an error (InvitationAlreadyResolved), and notes re-invite possibility. No contradictions.

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

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

The description is concise with two effective sentences. It front-loads the main action and adds necessary behavioral details without superfluous text.

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

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

Given the simplicity of the tool (single parameter, clear output from idempotency and error behavior), the description covers all necessary context. The presence of an output schema means return values are handled separately.

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, invitation_id, is fully described in the schema (100% coverage). The tool description does not add extra semantic information 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 clearly states the action: 'Decline a pending invitation addressed to the caller.' It differentiates from siblings like accept_invitation and cancel_invitation by its specific verb and target.

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 (declining a pending invitation) and provides context: 'The proposer may re-invite after this.' However, it does not explicitly state when not to use it or compare with alternatives.

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

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

Annotations already indicate destructiveHint=true. The description adds critical details: permanent removal, condition on shared bytes, no recovery path, and 404 with existence masking. 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?

Four sentences, each providing necessary information: action, effect, error case, return value. No redundancy. 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?

Given the simplicity of the tool (1 param, no output schema shown but description gives return JSON), the description is fully sufficient. It covers behavior, errors, and 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?

Only one parameter (image_id) with schema description already explaining it. The description references 'by id' but doesn't add new semantic context. Schema coverage is 100%, 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 hard-deletes a hosted image by id. It distinguishes itself from sibling tools like `delete_image_generator` by specifying the resource. The verb 'delete' and resource 'image' are 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?

It mentions ownership requirement and permanent deletion, implying when not to use (if you don't own the image or want recovery). It also notes existence masking, which is important context. However, it does not explicitly list alternatives for similar actions.

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 destructiveHint annotation, the description details the full extent of destruction: all versions, run records, anonymous run records are removed, no recovery path. It also covers edge cases like platform-managed generators surfacing as NotFound and no confirmation token needed. These behaviors are not apparent from annotations alone.

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

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

The description is well-organized: begins with the primary action, then covers permanence, alternatives, constraints, edge cases, and return value. While detailed, every sentence adds unique information, with no superfluous content. It is slightly lengthy but efficient for the complexity.

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

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

The description comprehensively covers the tool's context: scope, irreversibility, alternative, conflict conditions, edge cases for system generators, return format, and backup retention policy. Given the tool's destructive nature and with an output schema indicated, the description is fully complete.

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

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

The single parameter generator_id is described in the schema as a UUID, and the description adds that it accepts a UUID string, which is not explicitly in the schema format. It also clarifies the scope constraint (own generator) beyond the schema. Since schema coverage is 100% and the description adds practical context, a score of 4 is appropriate.

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

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

The description clearly states the tool 'permanently and immediately erase an image generator you own' with specific verb 'erase' and resource 'image generator'. It distinguishes from sibling tool 'revoke_image_generator', which is explicitly mentioned as an alternative.

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

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

Explicit guidance on when to use vs. revoke: 'Use revoke_image_generator if you want to deactivate the generator without erasing it'. Also mentions prerequisite about unpublishing template versions that reference the generator, providing clear conditions for successful invocation.

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

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

Annotations already set destructiveHint=true, but description adds critical details: immediate permanent removal of skill, versions, files, access grants; no recovery; encrypted backups age out within 90 days; no longer accessible via product surfaces. 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?

Description is concise, well-structured, and front-loaded with the key action. Every sentence adds value, with clear sections for consequence, alternative, and additional notes. No unnecessary words.

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

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

Given the tool's single parameter, existing annotations, and output schema, the description provides complete context: behavior, prerequisites (owner-only), scope (skill, versions, files, grants), irreversibility, and data retention policy. No gaps.

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

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

Only one parameter (skill_id) with full schema description coverage (100%). The description does not add new parameter semantics beyond what schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states it erases a skill permanently, using specific verb 'erase' and resource 'skill'. It distinguishes from sibling 'archive_skill' by naming it as a reversible alternative, providing clear purpose 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?

Explicitly states when to use (permanent deletion) and when not (use archive_skill for reversible action). Also notes owner-only requirement and applicability to both live and archived skills, offering comprehensive 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?

Description adds extensive behavioral context beyond annotations: permanence, no recovery, erasure of version row and attached files, backup retention window, version numbering gaps, and restriction against erasing current version. No contradiction with destructiveHint: true annotation.

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

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

Description is well-structured: starts with the core action, then lists consequences, alternatives, and constraints. Each sentence is informative and necessary, with no fluff.

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

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

Given the presence of an output schema and full input schema with annotations, the description covers all essential aspects: action, side effects, prerequisites, and alternatives. It is complete and self-contained.

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, but the tool description adds extra meaning: clarifies that version must be 'non-current' and that skill_id can be UUID, slug, or name. This provides useful context beyond the schema.

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

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

The description clearly states the verb ('erase') and resource ('single non-current skill version'), and distinguishes from sibling tools like archive_skill and delete_skill by specifying what each alternative 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?

Explicitly tells when to use this tool (for permanent erasure of a non-current version) and when not to (use archive_skill for reversible action, delete_skill for entire skill including current version). Also mentions owner-only access.

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, so the destructive nature is known. The description adds the behavioral detail that the handle is released for reuse, which is not deducible from annotations. However, it does not mention other consequences like deletion of team data or member dissociation.

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

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

The description is extremely concise with two sentences. Every word serves a purpose: stating the action, identifier methods, and side effect. No redundant or vague phrasing.

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

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

Given the complexity (destructive action, one parameter, output schema exists), the description covers the core purpose and side effect but lacks details on member handling, reversibility, or required permissions beyond ownership. The output schema may compensate, but the description could be more thorough for a deletion 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 schema provides 100% coverage for the single parameter, describing it as 'UUID or handle'. The description adds the crucial semantic that the team must be owned by the user, which is not in the schema. This helps the agent select the correct identifier.

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

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

The description clearly states the action ('Delete a team you own') and the resource ('team'). It specifies that deletion can be done by UUID or handle, and notes the side effect of releasing the handle. This differentiates it from sibling tools like 'remove_team_member' or 'transfer_team_ownership'.

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

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

The description indicates that the team must be owned by the user, providing a prerequisite. However, it does not explicitly state when not to use the tool (e.g., if the goal is to transfer ownership instead) or mention alternatives among siblings. Additional context about team member impact would enhance guidance.

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

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

The description goes far beyond the annotations by disclosing permanent deletion, absence of recovery, encrypted backup retention window, serving-gate refusal, fork parent pointer behavior, and ownership restrictions. This is model behavior transparency for a destructive op.

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?

Long but every sentence earns its place: permanence, recovery, alternative, serving gate, fork effects, ownership. Front-loaded with the most critical fact (permanent deletion), then consequences. No filler despite length.

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?

Coverage is exceptional for a destructive mutation: permanence, scope of deletion, backup retention, serving-gate refusal conditions, fork behavior, owner restriction, and compatibility with archived templates. With no output schema and destructive implications, all needed operational context is present.

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?

Parameter coverage in the schema is 100%: template_id is fully described as UUID or handle. The description adds ownership and NotFound behavior but no new parameter-specific semantics, 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?

States a specific verb ('erase'), the resource (template), and the key constraint (you own). It clearly distinguishes from archive_template by emphasizing permanence, and the deletion scope (template, versions, attached files, verification records) is precise.

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

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

Explicitly tells the agent when to use the alternative (archive_template for reversible removal), when deletion is refused (serving gate for live templates with published versions), and who may call it (owner only). This is complete routing 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 destructiveHint=true, but the description adds critical behavioral details: the permanent erasure, no recovery, the gap left in version numbers, the serving gate requirement, and Owner-only access with NotFound for other users. This goes well beyond the annotation's simple flag.

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 detailed yet concise (5 parts), front-loaded with the critical permanence warning, and every sentence provides utility. It uses bullet-like separate paragraphs for clarity without being verbose.

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

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

For a destructive, irreversible operation, the description covers all necessary context: the exact effect, prerequisites, alternatives, consequences to version numbering, and access control. The presence of an output schema also helps complete the picture. Nothing is missing for an agent to use it safely and 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 fully documents both parameters (100% coverage), so the baseline is 3. The description does not add significant new semantics; it only implies the version is the target of erasure bind. That is sufficient given the schema's clarity.

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 erases a single template version permanently and list the exact scope. It also distinguishes itself by name from siblings like delete_template and delete_skill_version, making it easy to differentiate.

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

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

The description provides explicit when-to-use guidance: only after unpublishing the version, and it names alternatives like archive_template and delete_template. This is a textbook example of clear usage direction.

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

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

Disclosures beyond annotations: lists exactly what gets permanently deleted (verifier, versions, run records, access grants), states no recovery path, mentions backup retention window, and notes no confirmation token needed. Does not contradict annotations.

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

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

Well-structured with front-loaded action statement, then detailed bullet points. Every sentence adds value without redundancy. Efficient use of text.

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

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

Given the destructive nature, the description covers all critical aspects: what is deleted, recovery, retention, constraints (serving gate), scope, and return value. No gaps remain for a safe and informed 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 already describes verifier_id as UUID or name. Description adds context: only works for user-scoped verifiers, and reaffirms the return value includes deleted: true. Schema coverage is 100%, so baseline is 3; the additional context raises it to 4.

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

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

Description clearly states the tool's purpose: 'Permanently and immediately erase a verifier you own'. It distinguishes from sibling tools like revoke_verifier and get_verifier, and specifies scope constraints.

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

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

Provides explicit when-to-use and when-not-to-use guidance: mentions revoke_verifier as alternative for deactivation without erasure, details serving gate conflict with published templates, and clarifies platform-managed/other's verifiers return NotFound.

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 well beyond the sparse annotations (readOnly=false, idempotent=false, destructive=false) by disclosing meaningful behavior: the model is validated against the pricing layer before creation, name collisions with system-scope generators are rejected, and the operation is non-idempotent because re-deploying appends a new version. This gives an agent an accurate mental model of side effects and failure modes.

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 organized into three clear blocks: purpose, versioning/scoping rules, and validation behavior. It is slightly long, but every sentence earns its place—there is no fluff or repetition of the schema. The most decision-relevant facts (create vs. append, system-scope collision, token requirement) are front-loaded.

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

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

Given the moderate complexity (nested payload, optimistic concurrency, scope constraints), the description covers the essential operational context: what it returns (version, version_token, config_hash, etc.), why it can fail (platform scope collision, model validation), and how it interacts with sibling calls (list/get for tokens). It doesn't spell out the exact return schema, but the description references the return fields adequately for an agent to proceed.

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 gives each parameter a descriptionhare and even adds a note explaining version_token semantics and deploy-time validation of model. It adds value on top of the schema by explaining exactly when expected_version_token is required (new vs. existing generator) and what a 'model must resolve to an authoritative price' means in practice. Minor gap: the description does not elaborate on generation_contract values beyond the schema's one-line summary, but the schema carries that load.

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 ('Deploy') and resource ('image generator'), then immediately states the core behavior: generators are created or versioned. It also answers 'what is this for' by explaining that skills reference generators to route image-generation calls to a model. This is unmistakably distinct from sibling tools like revoke_image_generator or list_image_generators.

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?

Clear operational rules are given: first deploy creates version 1, re-deploys append a version and require expected_version_token, and the token is obtained from deploy/list/get calls. There is also a concrete exclusion rule ('cannot deploy a new generator whose name matches an active platform-scope generator'). An agent knows exactly when and how to invoke this tool versus alternatives.

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

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

With annotations only providing readOnlyHint=false and no destructive hint, the description goes beyond by disclosing that verifiers are private and owner-scoped, that deploying a new verifier returns a conflict when no token is provided, and that the call returns a version token to persist. It also notes platform 'scope=system' verifiers are server-owned and cannot be deployed. A minor gap: it does not explicitly mention whether re-deploying is destructive to prior versions, though versioning implies append-only.

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 information-dense and front-loaded with the core purpose ric a clear one-sentence introduction dove. It uses paragraphs and a short list for few-shot examples, which aids scanning. However, it is quite long and repeats some schema details (input contract rules) that might have been left to the schema. Every sentence carries useful information, but it could be tightened slightly without loss.

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 an operation with versioning, optimistic concurrency, contract-specific input rules, and platform-scope restrictions, this description covers nearly everything an agent needs: the return payload fields, the token persistence requirement, the conflict behavior, and the input contract constraints. The only minor omission is an explicit note about whether re-deploying changes existing skill references, but that is not essential for invoking 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?

Schema coverage is complete (100% – all fields have descriptions), so the baseline is 3. The description adds value by explaining the version_token's role in re-deploys ('Persist version_token for the next re-deploy'), clarifying the input_contract enum semantics (text, text_image, image), and noting the few-shot examples' contract requirements. It does not restate parameter details already in the schema, which 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+resource: 'Deploy a semantic verifier (an LLM-judge check skills reference by id)'. It explains what the verifier does, distinguishes it from 'run_verifier' (which it names), and clarifies that skill references them by id. This clearly identifies the tool's role and separates it from sibling tools like get_verifier or delete_verifier.

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 names the alternative 'run_verifier' for executing verifiers, states that verifiers are owner-scoped, and explains when you cannot deploy (matching an active server-owned platform verifier). It also details the re-deploy path with expected_version_token, making it clear when to deploy vs. update, and notes that a new verifier must omit the token.

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?

Describes idempotency ('last-write-wins'), non-destructive nature ('soft signal, version stays fetchable'), and deprecation timing ('deprecated_at anchors on first call'). Fully aligns 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?

Four concise sentences, each adding essential information. No fluff. Front-loaded with main 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?

Explains return behavior (version stays fetchable), effect on other tools (fork_template, lookup_fork_lineage), and idempotent handling. Complete for a mutation tool with output schema.

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

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

Schema has 100% coverage. Description adds value by noting 'message is last-write-wins', which is beyond schema. Minor extra context.

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

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

Clearly states 'Mark one template version as deprecated' with specific resources. Distinct from siblings like delete_template_version.

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

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

Explicitly mentions 'Owner only' and describes soft-signal behavior versus alternatives. Lacks explicit when-not-to-use but context is clear.

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

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

The description reveals that the tool is a 'guided session' and does not persist results, requiring save_skill. However, it contradicts the readOnlyHint annotation by claiming to 'Create,' which is a mutation. This inconsistency severely damages transparency.

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

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

The description is two sentences, front-loading the purpose and providing actionable guidance. Every sentence earns its place with no redundancy.

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

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

The description covers the purpose and sequence, but the contradiction with annotations creates confusion. It does not explain the nature of the 'guided session' or output format, though an output schema exists. Overall, competent but marred by the annotation inconsistency.

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

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

With no parameters and 100% schema coverage, the description adds value by explaining the tool's process (guided session) and its outcome (design needing save_skill). It appropriately compensates for the lack of parameter details by clarifying behavior.

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

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

The description states 'Create a new skill from scratch,' but the readOnlyHint annotation indicates the tool is read-only, creating a contradiction. It distinguishes from save_skill by specifying the need to call it afterward, but the core purpose is undermined by the annotation inconsistency.

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 this tool (designing a new skill) and provides a clear follow-up action (call save_skill()). It implicitly distinguishes from save_skill by noting the persistence step is separate, but does not explicitly mention when not to use it.

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

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

Describes clearing failure state and preserving configuration, going beyond annotations. Could mention idempotency, but adds valuable 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?

Two sentences, no waste, front-loaded with main action. Efficient and clear.

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

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

For a simple tool with no parameters and an output schema, description covers functionality and side effects fully.

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?

No parameters, schema coverage 100%, baseline 4. No need for additional parameter info.

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 explicitly states the tool turns off automatic credit top-ups and distinguishes from siblings like configure_auto_top_up by noting it preserves configuration.

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?

Clear context for use (disable auto top-up) but lacks explicit when-not-to-use or alternatives; implied but not 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 this is a mutating, non-idempotent operation. The description adds valuable behavioral context: authentication is required, anonymous callers get AuthRequired, and the return value includes the new skill's id and lineage metadata. This goes beyond the annotations and helps the agent anticipate side effects and failure modes.

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

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

Three sentences with no fluff. The core action is front-loaded, and the authentication note and return value are stated compactly. 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?

The description covers the action, the ownership outcome, authentication requirements, and the return value. With an output schema present and 100% parameter coverage, this is nearly complete. It could mention what happens if the template is not public or if the caller already owns a skill with the same name, but those are edge cases.

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 adds context about the identifier format (UUID, @handle/slug, @handle/slug@vN) and the default behavior for name and version, but this is largely redundant with the schema. 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 ('Fork') and resource ('a public template into a private skill owned by the caller'), clearly distinguishing this from sibling tools like get_template, archive_template, or publish_template_version. It also specifies the ownership outcome, which is the core 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 implies when to use it: when you want to create a private skill from a public template. It doesn't explicitly name alternatives or exclusions, but the verb 'Fork' and the target 'private skill owned by the caller' make the use case clear. It also notes authentication is required, which is a usage prerequisite.

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

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

Annotations are all false (not read-only, not idempotent), so the description carries the disclosure burden and delivers richly: it reveals MCP-transport always authenticates (anonymous only via REST), billing deducted from monthly credit balance, BudgetExhausted (402) and AccountSuspended (403) propagation, the public/private visibility behavior, and that the prompt is never stored (only its hash persisted). This far exceeds what the annotations express and adds genuine safety/cost 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?

Front-loaded with the core purpose and well structured into a numbered resolution list and labeled sections (authentication, billing, visibility, returns). Every sentence carries information, and the length is justified by the tool's complexity (11 nested params). Minor redundancy: the visibility explanation is duplicated almost verbatim in the schema description, which could be trimmed.

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 high-complexity tool with a nested payload and an output schema (which covers the return shape), the description is remarkably complete: it covers authentication, billing and error propagation, the generator resolution order, mutual exclusivity, per-type reference_image_url rules, and prompt-privacy. Nothing an agent needs to call it 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?

Schema coverage is 100%, so each of the 11 payload fields is already documented, giving a baseline of 3. The description adds value on top: the generator resolution priority (deployed > model > tier > default), the generator/model mutual exclusivity rule, and the billing-per-image semantics for num_images. The visibility text is somewhat redundant with the schema, but the resolution-order context is net-new and material.

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+resource: 'Generate one or more images from a text prompt, billed to the caller's credits.' This clearly distinguishes the tool from siblings like get_image, list_images, upload_image, and delete_image. The scope (prompt→image, billing) is unambiguous and does not restate the name.

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

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

Extremely explicit guidance: a numbered resolution order for the generator (deployed ref > model > tier > default), the mutual exclusivity of generator and model, and the requirement/rejection rules for reference_image_url by generator type (image_to_image requires it, text_to_image rejects it). An agent is told exactly how to select among the parameter paths, with no inference required.

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, so the description does not need to emphasize safety. It adds context about retrieving monthly spend, but does not disclose any additional behavioral traits like response format or rate limits.

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

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

The description is a single, concise sentence that front-loads the main action ('Check your automatic credit top-up configuration') and then adds the spend detail. No unnecessary words.

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

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

Given no parameters and an output schema existing, the description is adequate. It tells the agent exactly what information is returned. A perfect score would require mentioning that it is read-only, but annotations already cover that.

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

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

With no parameters, the schema coverage is 100%. The description adds meaning by explaining what the tool retrieves, which is the top-up configuration and spend. Baseline for 0 parameters is 4.

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

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

The description uses the verb 'check' and specifies the resource 'automatic credit top-up configuration' along with 'this month's spend'. This clearly distinguishes it from sibling tools like 'configure_auto_top_up' and 'disable_auto_top_up', which are write 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 implies the tool is for viewing current settings and usage. It does not explicitly state when to use it versus alternatives, but the read-only nature is evident from the name and annotations, providing clear context with no 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?

Adds return content ('full image record including serving URL') and error behavior with existence masking, going beyond readOnlyHint annotation.

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

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

Three concise sentences: purpose, return value, error handling. No redundancy, 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?

With output schema existing, description sufficiently covers purpose, ownership, return content, and error behavior. Complete for a simple get 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?

Only one parameter with 100% schema coverage. Description adds no additional semantic detail beyond what schema provides.

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

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

Clearly states 'Fetch a hosted image by id' with specific verb and resource. Ownership requirement distinguishes it from tools like list_images, update_image, delete_image.

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

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

Explicit ownership constraint guides usage, but no mention of when not to use or alternatives like list_images or get_image_generator.

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

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

With annotations providing readOnlyHint, the description adds value by detailing the return payload, version pinning, and error conditions. This is exemplary transparency.

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

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

The description is extremely concise: three sentences that cover purpose, constraints, and return value, all without unnecessary words. It is front-loaded with the core action and resource.

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

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

With an output schema available, the description adequately covers the key aspects: what it returns, how parameters work, and error conditions. No gaps are apparent. The tool has low complexity (2 params, read-only), and the description is sufficient.

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

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

The schema already describes both parameters with 100% coverage, so baseline is 3. The description adds semantic value by clarifying that generator_id should be a user-owned UUID (not system), and that version pinning affects the output. This extra context elevates it above baseline.

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

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

The description clearly states the action ('Inspect'), the resource ('one image generator you own'), and the scope (its model and full config at head or pinned version). It distinguishes from system generators, which are not inspectable. This is specific and action-oriented.

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 that system generators are not covered, and that ownership is required. It implicitly distinguishes from listing tools and generation tools. However, it does not explicitly name alternatives like list_image_generators or generate_image. Still, the context is clear enough for an agent to infer when to use this get operation.

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 provide readOnlyHint: true, indicating a safe read operation. The description adds no additional behavioral context 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 a single sentence with no wasted words, efficiently communicating the tool's purpose and included 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 read-only resource with no parameters and an output schema, the description fully captures the tool's behavior and output. Completeness is high.

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 no parameters, so the description does not need to explain parameter semantics. Baseline of 4 is appropriate for zero 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 verb 'Return' and the resource 'referral program status', specifying two key outputs (shareable code and credits earned). It implicitly distinguishes from sibling 'redeem_referral_code'.

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

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

The description provides no explicit when-to-use or when-not-to-use guidance. Usage is implied by the tool's purpose, but it does not address alternatives among siblings.

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

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

Annotations indicate readOnlyHint=true, but description adds critical behavioral context: skills are private with cross-user reads masking as not-found, and owners can fetch archived skills. No contradiction is present.

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 sentences, front-loaded with purpose, no wasted words. Structure clearly separates purpose, usage instruction, default behavior, and privacy caveat.

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 presence of an output schema, the description adequately covers return content, versioning, identification methods, and privacy. Lacks error/rate limit info, but overall sufficient for a read tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description confirms default version behavior but adds no significant meaning beyond the schema. 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 retrieves a skill's runbook (body, outcome, tags) for execution, distinguishing it from listing/searching skills. It specifies the returned 'body' is a markdown runbook to be executed, not just displayed.

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 guidance to execute instructions rather than display them, mentions default latest version, and notes privacy/archival behavior. However, it does not explicitly state when not to use this tool versus alternatives like list_skills.

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 behavioral traits beyond the annotations: handling of SKILL.md, text vs binary files, size limits resulting in error field, and the need for view access. The annotations already indicate read-only (readOnlyHint=true), so the description adds valuable 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 concise with no unnecessary words, but the file-type handling information could be better structured with bullet points. It is front-loaded with the main purpose and quickly dives into details.

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 presence of an output schema, the description adequately covers all behavioral aspects: path matching, version pinning, file type handling, auth requirements. No gaps remain 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 coverage is 100%, so baseline is 3. The description adds the 'manifest matching' context for path, which is marginally beyond schema. It does not repeat existing parameter descriptions, which 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 'fetch', the resource 'single file from a skill version's file tree', and the method 'by path'. It distinguishes this tool from siblings like get_skill (which returns the manifest) and get_skill_files (which likely lists files).

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 that path must exactly match a manifest entry, suggests using get_skill to inspect the manifest, and specifies how different file types are handled. It also mentions the required view access. However, it does not explicitly contrast with get_skill_files 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?

Details error handling for unknown paths and budget exhaustion, ordering, and guarantee every path appears once. Annotations confirm read-only, and description adds significant behavioral context.

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

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

Well-structured, front-loaded with purpose, each sentence adds value 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?

Comprehensive coverage of return format, error modes, ordering, and budget limits; output schema exists but description still clarifies structure.

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 100% of parameters with descriptions; description adds practical context (e.g., paths must match manifest entries, version omitted uses latest, skill_id accepts UUID/slug/name).

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 fetches multiple files from a skill version's file tree, distinguishing from siblings like get_skill and get_skill_file.

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?

Explains inputs (paths must match manifest) and suggests using get_skill to see the manifest, but could be more explicit about when to use this vs. get_skill_file.

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 readOnlyHint annotation, the description adds valuable behavioral context: the returned body is an executable skill, non-owner reads carry an unverified-template safety banner, and the latest live version is fetched by default. These details inform the agent about execution semantics and safety expectations.

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 function, then adds essential behavioral details in short, focused sentences. No filler is present, and each sentence contributes meaningful information.

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

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

The description is complete for a read-only retrieval tool: it covers identifier formats, version behavior, access permissions, safety banner behavior, and the runbook execution semantics. The presence of an output schema means return-value details do not need to be in the description.

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 documents both parameters fully, including accepted identifier forms and version pinning, so the description does not need to compensate. The description adds minor useful context like 'latest live version by default' and 'anyone can read,' but it largely restates schema information.

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: 'Retrieve a public template's runbook' and clarifies the purpose: 'to run on the user's behalf.' It also distinguishes itself by noting the returned body is a skill to execute, not merely display, which differentiates it from related tools like get_template_file.

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 when to use the tool: to fetch a public template's runbook for the user. It explains access ('Anyone can read') and default behavior ('Latest live version by default'), but it does not explicitly name alternatives 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 readOnlyHint=true, but description adds valuable behavioral details: handling of text vs binary files, size limits (metadata+error), identifier formats, and safety banner for non-owners. 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?

Description is front-loaded with the main action and follows with necessary details. Six sentences each add information, but could be slightly more terse. Overall well-structured.

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

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

Given the output schema exists (context signals), description covers file behavior (text, binary, over-limit), identifier options, and access restrictions. Complete for the tool's complexity with 3 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 coverage is 100%, baseline 3. Description adds meaning beyond schema: explains identifier formats (UUID, @handle/slug, @vN), that path must match manifest, and version parameter's purpose. Adds significant value.

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

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

The description clearly states 'Fetch a single file from a template version's file tree by path', using specific verb and resource. It distinguishes from sibling tools like get_template (which returns the template manifest) and get_workflow_file (different resource).

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

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

Explicitly tells the agent to use get_template to see the manifest for path validation, and notes restrictions for non-owners and anonymous callers, providing clear context for when to use this tool vs alternatives.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false. The description adds value by noting that top-up configuration data (including this month's spend) is returned, and that it null if never configured. This provides behavioral context beyond annotations.

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

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

Two sentences, front-loaded with main purpose. Every sentence adds value 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 parameterless tool with an output schema, the description sufficiently explains the return values (balance, top-up config). No gaps.

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

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

There are no parameters, so schema coverage is 100%. Per guidelines, baseline is 4. The description explains what the tool returns, which is sufficient.

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

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

Description clearly states the tool checks monthly credit grant usage and remaining balance, and includes top-up configuration details. This specific verb+resource pairs well with the tool name and distinguishes it from siblings like get_auto_top_up.

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

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

Description indicates when to use (check credit usage and top-up info). It does not explicitly state when not to use or mention alternatives, but the tool's zero parameters and focused purpose make usage 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 declare readOnlyHint=true, but the description goes well beyond this by disclosing the exact payload returned (criterion, input_contract, etc.), the NotFound behavior for system/revoked/inaccessible verifiers, the config_hash for drift detection, and the access model for grantees. No contradiction with annotations; the read-only nature is consistently reinforced.

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 longer than average but every sentence earns its place: it front-loads the core purpose and scope, then methodically covers access rules, system exclusion, version defaults, and return payload. No redundancy or filler; it is an efficient, well-organized explanation.

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

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

The tool is complex enough (2 params, versioning, access control, specific return fields) that the description covers all necessary aspects: what is returned, when NotFound occurs, how version pinning works, and what caller permissions are required. The presence of an output schema reduces the burden, and this description exceeds that burden by preemptively explaining the key fields.

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?

Although schema coverage is 100%, the description adds substantial semantic depth: verifier_id is explained as accepting a UUID or an accessible user-scope name, and version is described as defaulting to the latest with explicit behavior when pinned. This goes far beyond the schema's terse descriptions and materially helps the agent pick and fill parameters correctly.

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 precise verb and resource ('Read a verifier's full definition') and immediately scopes it ('user-scoped verifiers only'), distinguishing it from run_verifier and list_verifiers. It also specifies what is excluded (platform/system verifiers), making its purpose unmistakable among 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?

While it does not explicitly name 'use list_verifiers instead for listing', it provides clear when-to-use context: reading a specific verifier's full definition, with explicit exclusions (system verifiers never returned) and access rules (owner and grantees can read). The version pinning guidance and the behavior for inaccessible/revoked verifiers further clarify when this tool is appropriate.

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

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

Annotations are minimal (non-read-only, non-destructive). The description adds valuable context about version history handling, which is not covered by annotations. No contradictions.

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

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

Two sentences, no wasted words. The key information is front-loaded and easy to parse.

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

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

Given the presence of an output schema (not shown but declared), all parameters are well-documented in schema, and the description covers the behavioral nuance of version history. Complete for this tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default and effect of include_history, and the flexible identifier formats for the grantee.

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: granting skill access to a user or team by identifier. It distinguishes from siblings like revoke_skill_grant and list_skill_grants by focusing on granting access.

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 on the include_history parameter and default behavior. Does not explicitly state when not to use this tool or compare with siblings, but the use case is straightforward.

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, destructiveHint=false, and idempotentHint=true. The description adds that it removes 'your direct grant', which provides context beyond the structured fields, but does not contradict annotations.

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

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

A single sentence that is front-loaded and contains no extraneous information.

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

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

For a simple tool with one parameter and an output schema, the description provides adequate context. It could briefly mention that a 'shared skill' is a skill granted within a team, but the current text is sufficient.

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

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

Schema covers the single parameter with a description of accepted identifiers. The tool description adds no additional meaning beyond the action.

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 'Remove your direct grant on a shared skill' uses a specific verb and resource, clearly distinguishing the action from siblings like grant_skill and revoke_skill_grant.

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

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

No explicit guidance on when to use this tool versus alternatives such as revoke_skill_grant. The implied use case is clear but not contrasted with similar 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?

Beyond the readOnlyHint annotation, the description adds critical security context: 'Never returns hashes or plaintext.' This discloses important behavioral traits about what the tool does not expose, which is valuable for an API key listing tool.

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

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

The description is three sentences long, front-loaded with the purpose, then describes the return format, and finally gives pagination instructions. Every sentence is essential, and there is no 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?

Given the tool has two well-documented parameters, an output schema, and is read-only, the description covers all necessary aspects: what it does, how to paginate, and what it does not return. It is complete for a simple listing 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 input schema already provides 100% coverage with descriptions for 'limit' and 'cursor'. The tool description does not add additional semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List', the resource 'your live (non-revoked) API keys', and distinguishes from siblings like mint_api_key or revoke_api_key. It is specific and unambiguous.

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

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

The description explains pagination behavior (page until next_cursor is null) and the return format. While it doesn't explicitly state when not to use it, the context of sibling tools makes it clear this is for viewing existing keys, not for creating or revoking.

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 declare read-only behavior. The description adds detail: lists only non-revoked generators, excludes platform-managed ones, and describes pagination behavior mirroring list_verifiers, all 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?

Three sentences covering purpose, exclusions, pagination, and return format. Front-loaded with main purpose, no unnecessary words.

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

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

For a list tool with simple pagination, the description fully covers what the tool does, what it returns (including field list), and its limitations (exclusions). No gaps given the output schema is provided inline.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by referencing list_verifiers pagination behavior, providing extra context for cursor usage.

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 the resource 'active (non-revoked) image generators owned by the caller'. It specifies exclusions (platform-managed) and scope, making it distinct from sibling 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?

Provides clear context that only user-owned generators are listed and platform-managed ones are excluded, informing when not to use this tool. However, no explicit alternatives are named for other use cases.

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 readOnlyHint annotation by detailing pagination behavior and return format ('Returns {items: [...], next_cursor: str | null}'). This provides critical behavioral context that helps an agent understand how to iterate results, with no contradictions to 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 concise at approximately 6 lines, front-loaded with the main purpose, and uses well-structured bullet points for filters and pagination. Every sentence adds value without redundancy, making it easy for an agent to parse.

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

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

Given the presence of an output schema and the description's coverage of filters, pagination, and return format, the description is fully complete for this tool. It addresses all necessary aspects without relying solely on structured fields.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on the source filter (e.g., explicitly mentioning 'generated' images) and explaining pagination cursor usage, which is not fully captured in the schema descriptions. This enhancement justifies a 4.

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

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

The description clearly states 'List hosted images owned by the caller, with optional filters,' specifying a verb (list) and resource (hosted images). This distinguishes it from sibling tools like get_image (single image) and delete_image, making the purpose immediately clear.

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

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

The description implies use for retrieving multiple images with optional filters but does not explicitly contrast with alternatives like get_image for individual images or upload_image. The usage context is clear but lacks explicit when-not or sibling differentiation.

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, and the description adds transparency by explaining cursor pagination, return format, and the effect of filter and state parameters.

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: first sentence states purpose, then parameter explanations with examples, then pagination and return format. No wasted words.

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

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

Given the parameter count, schema richness, and presence of output schema, the description fully covers behavior: listing with filters, state, and cursor pagination. No gaps.

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

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

Schema coverage is 100%, but the description adds significant value by providing examples and clarifying parameter behavior (e.g., 'filter="received" returns invitations where you are the recipient').

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

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

The description clearly states 'List invitations visible to the caller' and elaborates on filters and pagination, distinguishing it from siblings like accept_invitation or cancel_invitation.

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

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

The description implies usage for viewing invitations with various filters, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria.

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. The description adds value by specifying that it lists only direct grants (user and team) and that admin/owner access is required, going beyond the annotation.

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

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

The description is a single sentence, front-loaded with the action ('List'), and contains no unnecessary words.

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

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

With one well-described parameter, full schema coverage, and an output schema, the description provides all necessary context for the simple list operation.

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

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

Schema coverage is 100% with a clear parameter description. The description doesn't add new parameter info but reinforces the resource type. Baseline 3 is appropriate.

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

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

The description clearly states the action 'List', the resource 'grants on a skill', and specifies scope 'direct user and team grants', distinguishing it from sibling tools like grant_skill and revoke_skill_grant.

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 specifies 'Admin or owner only', providing clear access control guidance. While it doesn't mention alternatives, the context is sufficient for when 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?

The description clarifies that archived skills are excluded by default and only included if include_archived is true for owned skills. This adds detail beyond the readOnlyHint annotation. It also explains the response format and pagination cursor. No contradictions 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 brief and front-loaded with the main purpose, then follows with necessary details about pagination and archived skills. Every sentence adds value 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?

Given the presence of an output schema and six parameters (none required), the description covers pagination, archived inclusion, and filter scope. It omits some edge cases (e.g., behavior when no skills exist), but overall sufficiently completes the specification.

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

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

Schema coverage is 100%, so the schema already describes all parameters. The description adds minimal extra meaning for parameters (e.g., it doesn't elaborate on the 'filter' enum beyond what's in schema). The response structure explanation is relevant but not parameter-specific.

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 skills that are owned or shared, distinct from search_skills and list_skill_grants among siblings. It specifies the resource ('skills') and scope ('you own or shared'), making the purpose precise.

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 includes pagination instructions and mentions filtering via parameters, but does not explicitly differentiate when to use list_skills versus alternatives like search_skills or list_skill_grants. Usage context is implied but not formally guided.

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 declare readOnlyHint=true, confirming safe read behavior. The description adds value beyond annotations by disclosing that the owner appears via a synthetic row, which is a non-obvious behavioral trait. No contradictions detected.

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

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

The description consists of two short, clear sentences. It is front-loaded with the core purpose and includes an important behavioral note without any wasted words.

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

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

Given the simple tool (one parameter, read-only, with output schema), the description is complete. It covers the action, identification method, and a notable result behavior. The presence of an output schema means return values need not be detailed.

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

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

The schema description coverage is 100% for the single parameter team_identifier. The description mentions 'by UUID or handle', which mirrors the schema's own description. No new meaning is added beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states the verb 'List', the resource 'members of a team', and the identification method 'by UUID or handle'. It also adds a specific detail about the owner appearing via a synthetic row. Among siblings like add_team_member and list_teams, this tool's function is distinct.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives, such as listing teams or adding members. It lacks context about prerequisites or conditions that might warrant using this tool over others. While the purpose is clear, usage scenarios are left implied.

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 and openWorldHint=false, so the description doesn't need to restate that. It adds value by clarifying the scope ('visible to the caller') and that teams include both owned and member teams. No contradictions.

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

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

The description is a single, efficient sentence that front-loads the verb and resource. Every word is meaningful, with no wasted language. It is appropriately sized for the tool's simplicity.

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

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

Given the low complexity, full schema coverage, annotation support, and presence of an output schema (which documents return values), the description provides sufficient context. It covers what, scope, and behavior, meeting completeness requirements.

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

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

Schema description coverage is 100%, with the filter parameter fully described in the schema. The tool description does not add any additional parameter semantics beyond the schema, which meets the baseline. No extra context is needed.

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

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

The description 'List teams visible to the caller (owned + member of)' clearly states the action (list) and resource (teams), and specifies the scope of visible teams. This distinguishes it from sibling tools like 'list_team_members' (which lists members of a specific team) 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 does not explicitly state when to use this tool versus alternatives. However, the name and context (siblings) imply it's the go-to for listing teams. No usage exclusions or alternative recommendations are provided.

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

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

Annotations already mark readOnlyHint=true, so description adds value by specifying that archived templates are excluded unless include_archived is set, and only own archived are returned. No contradictions.

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

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

Two concise sentences, front-loaded with main purpose. Every sentence adds value; no fluff.

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

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

Covers key aspects: visibility, filtering, archived behavior. With complete schema, annotations, and output schema, description is sufficient for correct invocation.

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

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

Schema coverage is 100%, but description adds meaningful context for filter and include_archived parameters beyond the schema. Explains behavior of 'mine' filter and archived inclusion.

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 'List public templates' with a specific verb and resource. Distinguishes from sibling 'search_templates' by focusing on basic listing with filters.

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 contexts: 'Anyone can read', 'filter='mine' restricts to own templates', and archived behavior. Lacks explicit exclusion of when to use search_templates instead, but still guides usage well.

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=trueebb. The description adds meaningful behavioral detail beyond that: the inclusion/exclusion rules (owned plus grants, never scope=system), the anonymous-caller empty-list behavior, and the visibility constraint. These go beyond what the read-only annotation conveys.

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 dense sentences, each carrying distinct information: what is listed, what is returned, what is excluded, and which sibling to use for full config. 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?

Given the low parameter count, existing input schema, readOnly annotation, and output schema signal, the description covers visibility rules, exclusions, pagination, and the related get_verifier tool. Nothing an agent needs to choose or invoke this tool is missing.

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

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

Schema coverage is 100% for both parameters (limit and cursor), so the description is not obligated to re-explain them. It mentions next_cursor coupling but does not add new semantic value beyond the schema definitions.

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 active (non-revoked) verifiers visible to the caller." It clearly distinguishes this from get_verifier by specifying that list_verifiers returns the visible set while get_verifier reads full deploy-time config of a specific version. The scope (owned + skill-derived, excluding platform-managed system verifiers) 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?

The description explicitly directs users to get_verifier when they need the full deploy-time config, giving an actionable alternative and the condition that selects it. It also provides important context: anonymous callers get an empty list and platform-managed verifiers are never included.

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, so the agent knows this is a safe read operation. The description adds value by disclosing the specific behavioral scope: it checks upstream version status and unpublish state, and it returns a defined set of fields. It doesn't mention edge cases like what happens if the skill isn't a fork, but the read-only nature is well covered.

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

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

The description is a single, compact sentence that front-loads the core purpose and lists the return fields in parentheses. Every word earns its place; no filler or repetition of the tool name.

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

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

For a read-only lookup tool with one fully documented parameter and an output schema, the description is nearly complete. It explains what the tool checks and what it returns. The only minor gap is not stating behavior for non-forked skills or error conditions, but the output schema and read-only annotation cover most of what an agent needs.

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

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

Schema description coverage is 100%, so the schema already fully documents the single parameter (skill_id). The description doesn't add parameter-level detail beyond what the schema provides, but it does clarify the purpose of the parameter in context (acting on a forked skill). Baseline 3 is appropriate since the schema carries the load.

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 ('Check whether') and resource ('a forked skill's upstream template'), and clearly distinguishes its purpose from siblings like get_skill or get_template by focusing on fork lineage and upstream version status. It also lists the exact return fields, making the tool's scope unambiguous.

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

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

The description implies when to use this tool: when you need to know if a forked skill's upstream has new versions or was unpublished. It doesn't explicitly name alternatives or exclusions, but the context of fork lineage is clear enough to guide an agent away from generic get_skill/get_template calls. A brief mention of when not to use it would push this to 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?

Despite having annotations that are all false (no hints), the description explicitly warns that the secret is returned only once, a critical behavioral trait 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 extremely concise with a single sentence that front-loads the key action and includes a critical note about the one-time return, making it efficient and to the point.

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

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

For a simple creation tool with an output schema, the description is minimal. It covers the essential behavioral note but lacks broader context such as security implications, prerequisites, or how it fits into the overall key lifecycle.

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 describes the 'name' parameter fully (100% coverage), and the description adds no extra meaning beyond what the schema provides, meeting the baseline of 3.

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

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

The description clearly states the action ('Mint') and resource ('good_live_ API key'), and distinguishes from siblings like list_api_keys and revoke_api_key by its unique creation function.

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

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

The description implies the tool is used to create a new API key but does not provide explicit guidance on when to use versus alternatives like revoke_api_key, nor does it mention prerequisites or conditions.

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

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

The description discloses that only the description changes, while body, outcome, tags, and sibling files carry forward unchanged. It also states the requirement for edit access and explicit user approval before persisting. The annotations declare readOnlyHint=true, which aligns with the description's emphasis on local tuning and approval-gated persistence. The description adds meaningful 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.