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

With no annotations, the description carries the full burden of disclosing side effects; 'permanently' explicitly signals irreversibility and destructive behavior, which is the most important trait for a delete operation. It does not cover permission requirements or cascade effects on shares, but the core behavioral risk is stated.

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 with no filler, with the verb and object front-loaded. Every word ('permanently', 'delete', 'secret') earns its place.

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

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

For a simple one-parameter tool with no output schema, this is nearly complete: it identifies the action, the target, and the irreversibility. It loses a point only for not naming alternatives or side effects, but those are minor given the tool's simplicity.

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

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

The input schema already describes the single `name` parameter completely, and the description adds no additional parameter-level detail. At 100% schema coverage, the baseline 3 is appropriate.

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

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

Clearly states a specific verb ('delete') and resource ('a secret'), and the word 'permanently' distinguishes this destructive operation from siblings like rotate_secret or get_secret. Even without opening the schema, an agent can tell what this tool does.

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

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

No guidance on when to choose this over alternatives such as revoke_share or rotate_secret, and no exclusions or prerequisites. The use case is only implied by the tool's name and one-line description.

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. 'Get' signals a read-only operation and the description names the returned data. However, it does not disclose authentication requirements, that the data is scoped to the caller's own account, or whether invoking it has any quota/rate implications.

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

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

A single front-loaded sentence with zero waste: the verb aresource lead off, and each of the three listed items (tier, usage, limits) is a distinct, meaningful data category. Every word earns its place.

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

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

For a zero-parameter read tool with neither annotations nor an output schema, the description covers the essential ground by naming all three data categories returned. Missing auth context and explicit scope (caller's own account) are minor given the tool's simplicity.

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

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

The tool takes zero parameters, so the schema has nothing to document and the description is not required to explain any. Baseline 4 applies; the description still adds value by telling the agent what the empty call will yield (tier, usage, limits).

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?

Specific verb 'Get' + resource 'your account' + three named data categories (tier, secret usage, limits). The description clearly distinguishes this from all siblings, which strictly target secrets or shares, making the tool's identity 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?

No explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The context implies this is the account-level status/quota check, likely performed before secret operations, but that usage context is left to inference 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?

With no annotations provided, the description carries the full disclosure burden and does well: it revealss decryption behavior, the null-when-not-found edge case, and tier-gated version retrieval. It stops short of stating authorization requirements or what the default version is (presumably latest), but covers the key behavioral traits for a simple read 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 sentences, front-loaded with the primary purpose, and every clause earns its place: 'Retrieve and decrypt', null-not-found, and version support. 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?

For a simple two-parameter read tool with no output schema, the description covers the core behavior: what it does, the not-found edge case, and version handling. Minor gaps like default version behavior and how this differs from get_shared_secret are not addressed, but they do not prevent 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 description coverage is 100%, so the baseline is 3. The description reinforces the version tier detail already present in the schema but adds no new meaning for either parameter beyond behavior like null-return, which is behavioral rather than parameter-level 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 uses a specific verb and resource: 'Retrieve and decrypt a secret value by name.' It clearly differentiates from siblings by naming the operation (retrieve+decrypt) and its scope (by name), distinguishing it from set_secret, list_secrets, delete_secret, and get_shared_secret without ambiguity.

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

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

Usage is implied through the purpose — you use this to get a named secret's value — and the version/tier note provides some context. However, there is no explicit when-to-use versus alternatives like get_shared_secret, inject_secrets, or list_secrets, nor 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 disclosure burden and does add meaningful behavioral context: it states an authentication requirement (none) and the validity conditions for a successful retrieval. It does not describe what happens on failure or whether retrieval consumes a read, but 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 deliver the essential facts with no filler, and the action plus the key constraint are front-loaded. Every sentence earns its place.

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

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

For a single-parameter read operation with no output schema, the description is nearly complete: it gives the input source, auth context, and success conditions. Its only gap is lack of explicit failure/error behavior, which would be nice but not essential for this simple retrieval 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 single parameter is already fully documented in the schema with the description 'The share token from a share link.' The tool description only restates the share-token concept without adding syntax, format, or additional semantic detail, so the schema-driven 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?

The description states a specific verb and resource: 'Retrieve a shared secret using a share token.' This clearly distinguishes it from the sibling get_secret by emphasizing the share-token path and the no-authentication requirement.

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 establishes clear usage context by stating that no authentication is required and that the share must be non-expired, non-revoked, and within its read limit. It does not explicitly name alternative tools or provide when-not-to-use guidance, so it falls just short of a 5.

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

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

With no annotations, the description carries the behavioral burden, and it does disclose the side effect on process.env and the return value (count of secrets injected). It does not mention whether existing env vars are overwritten, but for a zero-parameter startup utility this is adequate 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 concise sentences that front-load the core behavior and quickly state usage and return value. Every sentence earns its place; there is no filler 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 zero-parameter, no-output-schema tool, the description fully explains what happens, what is returned, and when to call it. Nothing critical is missing for an agent to invoke it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed; the schema also has no properties.

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 ('Load all secrets into the process environment') and a clear resource ('all secrets'), with a concrete effect on process.env. It also distinguishes itself from siblings like get_secret and list_secrets by being a bulk environment-loading operation.

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

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

It gives an explicit usage context: 'Use at agent startup to make all stored secrets available as env vars.' This clearly tells the agent when to invoke it, though it does not explicitly state when not to use it or name alternative tools.

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

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

With no annotations, the description carries the burden and does disclose the key behavioral fact that values are never returned. It also clarifies the operation only returns names, which prevents agents from expecting secret content. It does not address auth or side effects, but for a list op the core behavioral truth is well stated.

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, purposeful sentences. The first states the action and scope; the second adds an essential restriction. No filler 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 list tool with no output schema, the description adequately communicates the operation's result and its most important constraint. Pagination is handled by the schema's cursor parameter, so the absence of a detailed output format description is a minor gap rather than a blocking one.

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 each parameter (limit, cursor, prefix) already has a clear description in the schema. The description adds no extra parameter-level meaning, so baseline 3 applies.

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

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

The description uses a specific verb ('List') and resource ('secret names') with explicit account-level scope. It clearly differentiates from siblings like get_secret by stating values are never returned in list operations.

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

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

The description gives clear context for when to use this tool: when you need to enumerate secret names on the account. It does not name alternative tools directly, but the caveat about values not returned implies a separate operation is needed for values, offering reasonable routing guidance without explicit exclusions.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that only non-revoked, non-expired shares are returned and that a Builder+ tier is required, which is meaningful context beyond a bare list operation. It does not describe pagination, ordering, or response shape, but those are minor for a simple list 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 a single compact sentence followed by a short tier requirement. Every word adds value: it defines the resource, the active-status filter, the account scope, and the access requirement. There is no fluff or redundant 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?

For a low-complexity tool with one optional parameter and no output schema, the description covers the essential purpose, scope, and access tier. It leaves return-format and pagination details to inference, which is a minor gap but not a blocker for selecting or 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?

There is one optional parameter, secretName, and the schema already documents it fully with 'Optional: filter shares by secret name,' giving 100% schema description coverage. The description adds no parameter-level detail, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List all active share links on the account.' The qualifier 'active (non-revoked, non-expired)' defines the exact subset and distinguishes this from share_secret, revoke_share, and get_shared_secret. It is also clearly different from list_secrets because it targets shares, not secrets.

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

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

The description gives a clear use case: list active share links for the account, and it adds a prerequisite by noting the Builder+ tier requirement. It does not explicitly name alternatives or when-not-to-use conditions, but the resource scope is specific enough that an agent can select it appropriately.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses immediate effect and tier requirement, but omts ownership/permission requirements and whether revoking is idempotent or irreversible, which would be useful for a mutating 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 a single front-loaded sentence with no redundant words; it efficiently states the action, timing, effect, and access requirement.

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

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

For a one-parameter mutating tool with no output schema, the description plus the schema's param origin note cover the essential elements. Explicit irreversibility or error behavior would improve completeness, but it is adequate.

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

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

Schema coverage is 100% and the single param (shareId) already has a description noting it comes from list_shares, so the tool description adds no additional param semantics. Baseline 3 applies.

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

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

The description uses a specific verb ('Revoke') with a clear resource ('a share link') and states the intended effect ('so it can no longer be used'), which differentiates it from sibling tools like share_secret and list_shares.

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—when a share link must be invalidated immediately—and notes the Builder+ tier requirement. It does not explicitly name alternatives or exclusion cases, but the purpose is unambigous.

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 of behavioral disclosure. It does state a meaningful side-effect (re-encryption under a fresh key, implying the secret value is preserved) and an entitlement gate ('Requires Pro tier'), but it stays silent on whether rotating breaks active shares (relevant given share_secret/revoke_share siblings), on reversibility, and on required permissions beyond tier. For a mutating tool with zero annotation coverage, that is a partial but not complete 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?

Three short sentences, each earning its place: operation semantics, when to use, and the tier prerequisite. The core verb is front-loaded, with no filler and no repetition of the title.

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

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

For a low-complexity tool (one required parameter, no output schema, no enums), the description covers purpose, timing, and a prerequisite. The only notable gap is the effect of rotation on shared secrets and existing ciphertext references, which is relevant given the sharing siblings. Overall it is complete enough for an agent to call the tool correctly.

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

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

Schema description coverage is 100% — the single 'name' parameter is already documented as 'Secret name to rotate' — so the baseline of 3 applies. The description adds no parameter-level detail such as format, required permissions, or constraints on 'name.' It neither compensates for a schema gap nor harms; the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource — 'Re-encrypt a secret with a fresh Data Encryption Key' — which precisely distinguishes the operation from every sibling (set_secret creates, get_secret reads, delete_secret destroys, list_secrets enumerates). The mechanism (fresh DEK) adds precision beyond the generic title 'Rotate Secret.' An agent can reliably know what this tool does without opening the schema.

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

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

'Use after KMS key rotation or as a security best practice' provides explicit, actionable timing context. It does not explicitly name alternatives or when-not-to-use, but no sibling offers rotation, so the contrast is implicit. This is clear context with no exclusions, just shy of the full when/when-not/alternative rubric for a 5.

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

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

With no annotations provided, the description carries the full burden, and it delivers substantive context: values are envelope-encrypted server-side with AWS KMS and the call returns a new version number, which implies versioned storage. It does not explicitly state overwrite consequences for an existing name or auth requirements, but the disclosed traits go well beyond a bare mutation claim.

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 earning its place: the operation, the encryption behavior, and the return value. The purpose is front-loaded with no filler or restatement of the title.

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 mutating tool with no output schema and no annotations, it discloses the two most decision-relevant traits — server-side KMS encryption and the version-number return — while the schema covers all parameters. The remaining gaps (explicit overwrite/versioning semantics and sibling routing) are either partially implied by 'update' and 'new version number' or already captured under usage guidance.

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?

Scema description coverage is 100%, with each of the five parameters already documented — including examples, ISO 8601 format, and the mutual exclusivity between expiresAt and ttlSeconds. Per baseline, the description need not repeat parameter detail, and it does not add param-specific value, which is acceptable here.

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-resource pair ('Store or update a secret') plus a concrete return value ('Returns the new version number'). Against siblings like get_secret, delete_secret, and rotate_secret, this is the only tool that writes an arbitrary secret value, so a model can distinguish it without opening 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 verb 'Store or update' implies the use case — creating or replacing a secret value — but no alternatives are named and no exclusions are given. An agent must infer that rotate_secret handles rotation, get_secret handles reads, and delete_secret handles removal. This is implied guidance, not explicit routing.

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

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

With no annotations present, the description carries the transparency burden. It discloses several key behaviors: the link is time-limited and read-only, the returned shareToken can retrieve the secret without authentication, and a paid tier is required. This goes well beyond a bare 'Create a share link' and covers the most important operational traits.

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

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

The description is two tight sentences with no filler. The main action and return value are front-loaded, the access requirement is stated last, and every phrase adds useful 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 covers the essential facts needed to call the tool: what it does, what it returns (shareToken), and the Builder+ tier requirement. The schema covers parameter details. It does not explicitly say the secret must already exist, but that is implied by 'for a secret' and is a minor gap.

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

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

The input schema provides 100% coverage with descriptions for all four parameters (name, scope, maxReads, expiresInSeconds). The description itself does not add parameter-level meaning, so the baseline of 3 applies. It does hint at 'time-limited' and 'read-only', which loosely map to expiresInSeconds and the nature of the share, but not specifically.

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

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

The description clearly identifies the action ('Create'), the resource ('share link for a secret'), and the core outcome ('Returns a shareToken'). It distinguishes the tool from siblings like get_secret or delete_secret by focusing on share-link creation, though it does not explicitly name a competing sibling.

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 clearly states the intended use case: creating a time-limited, read-only share link. It also provides a prerequisite ('Requires Builder+ tier'), which helps the agent decide whether the tool is even callable. It does not explicitly say when not to use it or name alternatives, but the context is clear.

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