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

With no annotations supplied, the description carries the full burden and adds meaningful behavioral context: it discloses role requirements (Member vs Admin), environment-specific URI validation rules, and the confirmation requirement for LIVE mode. It does not detail failure modes or duplicate handling, but it covers the key operational constraints.

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

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

The description is compact and well-structured: a one-line purpose followed by two clearly separated mode-specific rules. Every sentence provides necessary information with no redundancy or filler.

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

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

For a mutation tool with five parameters, no annotations, and no output schema, the description covers the essential call constraints: environment differences, permission levels, URL policies, and confirmation. Minor gaps like duplicate handling or post-add behavior are less critical for correct invocation.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by tying uri and environment semantics together: TEST allows localhost, LIVE does not, and confirmation is conditionally required. This goes beyond the raw schema definitions and helps the agent construct valid calls.

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

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

The description states a specific action, resource, and purpose: 'Add a redirect URI to an AgeKey application.' It clearly differentiates from the sibling tool remove_redirect_uri by name and operation, so an agent can immediately know what the tool does.

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

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

The description provides clear mode-specific guidance: TEST mode allows any valid URL and requires Member role; LIVE mode requires HTTPS, no localhost, Admin role, and confirmation. It does not explicitly name alternatives, but the operation is self-contained and the sibling remove_redirect_uri implies the inverse case.

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

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

With no annotations provided, the description carries the full disclosure burden and does meaningful work: it reveals the return payload ('Returns test credentials') and flags a one-time visibility constraint ('secret shown only once!') that the agent must act on by capturing the secret immediately. Minor gaps remain around error behavior and idempotency, but the most operationally critical trait is disclosed.

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 short sentences, each carrying distinct value: the action itself, the return behavior with a critical caveat, and the authorization requirement. The core purpose is front-loaded with zero filler or redundancy.

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

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

For a simple 3-parameter creation tool with no output schema and no annotations, the description covers the essential operational facts: what the call returns and the one-time secret warning. It omits the full response structure and error scenarios, but the explicit return-value statement partially compensates for the missing output schema.

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

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

Schema coverage is 100%, with all three parameters (name, orgId, description) already described in the input schema. The tool description adds no parameter-specific meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Create a new AgeKey application.' This is the only creation tool among siblings like list_applications, get_application, add_redirect_uri, and rotate_credentials, so the agent can immediately distinguish it without opening any schema.

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

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

Usage is implied by the purpose — an agent should call this when a new application needs to be created — and the permission precondition ('Requires Admin role or higher in the organization') provides useful authorization context. However, it never explicitly names alternatives or states when-not-to conditions (e.g., 'to modify an existing app, use add_redirect_uri instead').

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses that the tool shows header, payload, expiration status, and a human-readable explanation. However, it does not mention whether the token is validated (signature check) or just decoded, whether it makes external calls, or any side effects. For a read-only decoding tool, this is adequate but not rich.

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

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

The description is a single sentence that is front-loaded with the main verb and resource, then lists the key outputs. Every word earns its place; no fluff or repetition.

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

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

For a single-parameter decode tool with no output schema, the description covers the main outputs (header, payload, expiration status, explanation). It doesn't specify the exact structure of the output, but the description's mention of 'human-readable explanation' gives a sense of what to expect. Given the tool's simplicity, this is nearly complete. A small gap is not stating whether the token is verified or just decoded.

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

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

Schema description coverage is 100%: the only parameter 'token' is described as 'The JWT token to decode'. The description adds the context that it's an AgeKey JWT token and that the output includes expiration status and explanation, which adds some meaning beyond the schema. Baseline 3 is appropriate since the schema already documents the parameter.

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

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

The description clearly states the tool's function: 'Decode and explain an AgeKey JWT token.' It specifies the resource (AgeKey JWT token) and the action (decode and explain), and lists the outputs (header, payload, expiration status, human-readable explanation). This distinguishes it from siblings like explain_error, which explains errors, and get_code_sample, which provides code samples.

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

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

The description implies usage: when you have an AgeKey JWT token and need to decode it. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The sibling tools are mostly about organization/application management, so the context is clear, but the description doesn't explicitly guide selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates the tool returns an explanation with common causes, solutions, and documentation links, which suggests a read-only lookup. However, it does not explicitly state that the tool has no side effects, does not mutate anything, or require specific permissions. For a simple explanation tool, this is a minor gap, but more transparency would improve the score.

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

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

The description is a single, front-loaded sentence that states the main action, the target resource, and the expected content. There is no redundant phrasing or filler, and every word contributes to the agent's understanding. This is an ideal length for a tool of this 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?

For a tool with two well-documented parameters and no output schema, the description is nearly complete. It explains what the tool does and what it returns, and the schema covers parameter semantics. The only missing piece is an explicit statement about whether the 'errorDescription' parameter is used to tailor the explanation, but this is optional and not critical for correct invocation. Overall, the definition is sufficient for an agent to use it correctly.

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

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

The input schema covers 100% of parameters with descriptive text, so the baseline is 3. The description adds no additional parameter-specific detail beyond what the schema already provides. It mentions the error code in the purpose but does not elaborate on how 'errorDescription' influences the explanation, leaving all parameter semantics to the schema.

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

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

The description states a specific verb ('Get') and resource ('a detailed explanation of an AgeKey/OIDC error code'), and mentions the included content (causes, solutions, links). It is distinct from all siblings, which deal with organizations, applications, credentials, JWT decoding, and code samples, so there is no confusion about which tool does what.

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 its usage context (when you have an error code) but does not explicitly state when to use it versus alternatives, nor does it provide any exclusions or conditions. Since no sibling performs a similar function, the implicit guidance is adequate, but it lacks an explicit 'use when' statement.

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

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

With no annotations, the description carries the behavioral burden. It usefully discloses that the response includes credentials and redirect URIs, and 'Get' implies a read-only retrieval. However, it does not state auth requirements, whether full secret values are returned, or any side-effect guarantees.

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

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

The description is a single, front-loaded sentence with no filler. Every phrase contributes meaning, naming the action, the resource, and the key contents of the response.

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 two-parameter getter, the description is minimally adequate, but with no output schema it leaves 'detailed information' vague and only names credentials and redirect URIs. It does not cover auth, error behavior, or the full set of returned fields, so an agent has some reasonable expectations but not complete context.

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

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

Schema description coverage is 100%, so the schema already documents appId and orgId adequately. The description adds no additional parameter-level meaning beyond identifying the target as a specific application, which aligns with the baseline score of 3.

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

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

The description states a specific verb, resource, and scope: 'Get detailed information about a specific AgeKey application including credentials and redirect URIs.' It clearly differentiates from list_applications by focusing on a single application, but it does not explicitly clarify how it overlaps or differs from the sibling get_credentials tool.

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

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

The wording implies this tool is for retrieving detailed information about one known application rather than listing apps, but it offers no explicit when-to-use or when-not-to-use guidance and does not mention alternatives like get_credentials or list_applications.

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

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

With no annotations, the description carries the full burden. The verb 'Get' implies a read-only operation徒 and the pre-fill mention adds behavioral context, but the description does not explicitly state that no resources are modified, whether authentication is required, or what side effects (if any) occur.

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 filler, with the core purpose front-loaded and the optional behavior mentioned second. 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 tool has no output schema, so the return value format (e.g., snippet text, file, instructions) is left unspecified. The schema adequately covers parameter choices via enums and descriptions, but the interplay between flow and step, and the shape of the returned code sample, are not explained.

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's phrase 'pre-fill with your app credentials' adds a bit of meaning to appId, but the schema already documents that param as 'Optional application ID to pre-fill in the code sample.' No additional semantic value is provided for flow, step, or language.

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 integration code samples for AgeKey, with 'Get' as a specific verb and 'code samples' as the resource. It is distinguishable from sibling tools like list_applications or get_credentials, which target different resources. It doesn't explicitly mention the flow/step dimensions, but the schema covers those.

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

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

No explicit when-to-use or when-not-to-use guidance is provided, and no alternatives are named. The only contextual cue is 'Optionally pre-fill with your app credentials,' which hints at the appId param but does not explain when this tool should be selected over 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?

With no annotations, the description must carry behavioral disclosure. It does state the tool retrieves three named credential fields, implying a read operation. It does not disclose whether any permissions are required, whether the secret is the current active secret, or how errors surface. That is a meaningful gap for a no-annotation tool.

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

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

Two short sentences with no filler; the core action and return fields are front-loaded. The second sentence adds actionable parameter guidance, though it largely repeats schema content.

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

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

For a getter with no output schema and no annotations, the description adequately names the returned values and lists all required parameters. It omits any note that secrets are sensitive or that rotation exists elsewhere (rotate_credentials), and it gives no error/availability context, so it is minimally 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 description coverage is 100%, so the baseline is 3. The description's mention of 'test' or 'live' and 'Requires orgId' only restates what the schema already documents via enum and property descriptions; it adds no new semantic 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 verb 'Get' plus resource 'credentials for an AgeKey application' is specific, and enumerating the returned fields (App ID, Secret, Authority URL) makes the purpose unambiguous. However, it doesn't explicitly distinguish from sibling tools like get_application or rotate_credentials, so it stops short of a 5.

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

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

The description tells the caller to specify 'test' or 'live' and that orgId is required, which gives usable context for invoking. It does not state when this tool is preferred over rotate_credentials or list_applications, nor does it give any 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It does add value by stating the return content (app names, IDs, credential status), but it says nothing about pagination, result limits, ordering, or error behavior for an invalid orgId — relevant gaps for a 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?

Two short sentences with zero filler. The primary action is front-loaded, and the return summary earns its place by telling the agent what output to expect.

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 list tool, the description is adequately complete: purpose, scope, and return content are covered, and the schema fully documents the one parameter. Remaining gaps are minor — no mention of pagination behavior or failure semantics for an invalid org — but they do not block a competent agent from calling it correctly.

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

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

Schema description coverage is 100% and the schema already documents orgId as 'The organization ID to list applications for.' The description adds no parameter-level detail, which aligns with the baseline 3 for full schema coverage.

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

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

States a specific verb ('List'), resource ('applications'), and scope ('in an AgeKey organization'), and tells what it returns. The bulk-listing phrasing ('all applications') and org scoping distinguish it from siblings like get_application (singular fetch) and list_organizations (different resource) without needing to inspect their schemas.

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 need the full set of applications in an org — but it gives no explicit guidance about alternatives, such as using get_application when a single app's details are needed. No conditions or exclusions are 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?

With no annotations, the description carries the burden and it does disclose the essential behavior: it is a read-only listing operation that returns organization details, the caller's role, and the number of applications. It doesn't mention pagination or rate limits, but given the zero-parameter, list-only nature, the core behavior is transparent.

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

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

Two short sentences, with the action front-loaded and every phrase carrying information. No filler, repetition, or irrelevant detail.

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

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

For a zero-parameter list tool with no output schema, the description is complete enough: it states the scope and key returned fields. It could be more complete with pagination or ordering details, but those are minor for an operation of this simplicity.

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

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

The tool has zero parameters, so the schema is trivially fully covered. The description adds relevant context about what is returned, and there are no parameter semantics left to clarify.

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

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

The description uses a specific verb ('List'), names the exact resource ('AgeKey organizations'), and scopes it to those the caller has access to. It also previews the returned fields (role, application count), making it easy to distinguish from sibling list_applications.

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 this tool is for enumerating organizations visible to the caller, but it does not explicitly state when to choose this tool over siblings such as list_applications or get_application. There is no exclusion guidance or alternative mention, leaving the agent to infer placement from the name.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it states required roles, the need for confirmation in LIVE mode, and explicitly warns that removing a live URI will immediately break production integrations. This makes the destructive nature and authorization requirements fully transparent.

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

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

The description is compact and front-loaded: it states the core action first, then provides environment-specific role requirements, then the warning. Every sentence carries necessary information with 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?

The tool is a moderately complex destructive operation with 5 parameters and no output schema, but the description covers the critical call semantics: what is removed, from which environment, who may do it, what confirmation is needed, and the consequence of the action. No additional information is necessary for an agent to invoke it correctly.

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

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

The input schema has 100% parameter coverage, so the baseline is 3. The description adds value beyond the schema by explaining the real-world significance of the environment parameter and confirmation requirement, and by clarifying that confirmation becomes mandatory in LIVE mode.

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

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

The description uses a specific verb ('Remove') with a precise resource ('a redirect URI from an AgeKey application'), making the tool's purpose immediately clear. It is unambiguously distinct from sibling add_redirect_uri, which performs the opposite operation.

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

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

The description provides clear context for when the tool applies by distinguishing TEST vs LIVE modes and specifying role requirements for each. It does not explicitly compare to alternatives or state when not to use it, but the opposite sibling is obvious from the name and the usage context is strong.

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

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

No annotations are provided, so the description carries the full burden. It discloses the destructive consequence ('Old credentials are invalidated immediately!'), role-based authorization requirements, and the confirmation phrase requirement. This is exactly the kind of behavioral context an agent needs for a credential-rotation operation.

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

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

The description is compact and front-loaded: the core action is stated first, then mode-specific requirements, then the critical warning. Every sentence earns its place, and the warning is appropriately emphasized.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential context: what it does, who can do it, what confirmation is needed, and the destructive consequence. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the confirmation phrase requirement and tying it to the environment parameter, which goes beyond the schema's enum description. It doesn't add much for appId/orgId, but the schema already covers those.

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 ('Rotate credentials') and the target resource ('an AgeKey application'), and distinguishes it from sibling tools like get_credentials and create_application. The verb is specific and the scope is unambiguous.

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

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

The description explicitly states role requirements for TEST vs LIVE modes and requires a confirmation phrase for LIVE. It also warns about immediate invalidation, which tells the agent when to use caution. This is strong usage guidance.

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