seekrit — secrets for agents

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds the behavioral trait 'most recent first' ordering, which is not in annotations. This adds value beyond structured fields. Missing details like pagination or rate limits are acceptable given strong annotations.

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

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

The description is a single concise sentence (7 words) that front-loads the main purpose. However, given the parameter deficit, a slightly longer description with parameter hints would be more effective without sacrificing conciseness.

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 3 parameters, 33% schema coverage, and no output schema, the description should explain the return value and how to use parameters. It does not mention output format or which parameters are supported. The description is incomplete for an agent to understand usage 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?

Schema description coverage is only 33% (only the 'action' parameter has a description). The tool description does not explain any parameters, leaving 'org' and 'limit' entirely undocumented. The description should compensate for low coverage but does not.

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

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

The description clearly states the tool reads the organization's audit trail with most recent first ordering. It uses a specific verb 'Read' and resource 'audit trail', and distinguishes itself from sibling tools which are more specific listing 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 provides no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use advice. While it is likely the only audit tool among siblings, it lacks explicit usage context like prerequisites or typical 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by detailing what is shown (plan, entitlements, usage, upgrade actions). However, it does not describe the output format or behavior for missing org parameter, leaving minor transparency gaps.

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: the first states the primary function, the second provides a usage tip. It is front-loaded, concise, 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?

Given the simple tool (one optional parameter, no output schema), the description covers the purpose and available data categories. It lacks parameter documentation and return structure details, but the context signals and annotations partially compensate.

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 0% schema description coverage, the description must explain the 'org' parameter. It only implies the parameter's role by mentioning 'the org's plan', but does not specify whether it is required, optional, or what the default is (if omitted). This is insufficient for a single 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 shows the org's plan, entitlements, current usage, and upgrade actions. It specifies the resource (org billing) and the action (show), and distinguishes itself from sibling tools like list_apps or create_group by focusing on billing diagnostics.

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 advises reading this tool when a create action is refused due to a plan limit. This provides clear when-to-use guidance and implies it is a diagnostic read before creation, contrasting with mutation tools like create_group.

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, indicating safe, non-destructive behavior. The description adds the key behavioral detail about priority conflicts ('higher position wins on name clashes'), which is not in annotations. However, it does not describe potential side effects or return behavior.

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

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

The description is very short (two sentences) and front-loaded with the main action. However, the second sentence 'Keyless.' adds minimal value and could be expanded or moved to annotations. Every sentence should earn its place; this one does not.

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

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

Given 5 parameters (3 required), no output schema, and annotations that partially cover behavior, the description is incomplete. It does not explain what happens if the group is already composed or how the position parameter affects composition. The agent lacks essential context to use the tool confidently.

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 0%, and the description provides no information about any of the 5 parameters (app, env, org, group, position). The term 'Keyless.' is irrelevant to parameter meaning. The agent must guess parameter semantics from names alone.

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 'Compose a group into an application environment', which is a specific verb+resource. The additional clause 'higher position wins on name clashes' explains the unique behavior, distinguishing it from siblings like 'uncompose_group' or 'create_group'.

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 lacks any guidance on when to use this tool versus alternatives. With siblings like 'uncompose_group' and 'create_group', the agent gets no help in choosing. The term 'Keyless.' is cryptic and does not provide usage context.

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

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

Annotations declare non-readonly and non-destructive. Description adds that the tool is 'Keyless' and mentions local crypto plane, providing behavioral context beyond annotations. No contradiction.

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

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

The description is two sentences with no wasted words, but the second sentence is slightly ambiguous. Overall, 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 tool has 3 parameters, no output schema, and moderate complexity, the description provides the core purpose but lacks details on parameter usage and the meaning of 'Keyless' or 'local crypto plane'. It is adequate but not 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 0%, and the description does not explain any of the three parameters (org, name, slug). The description adds no 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 clearly states the action (create) and the resource (application in an organization). It distinguishes from sibling tools like delete_app or list_apps by mentioning the subsequent step of creating environments with create_env.

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 a workflow (create_app then create_env) but does not explicitly state when to use this tool versus alternatives or when not to use it. Provides some context but lacks direct 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 this is a mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds 'Keyless' hinting at no auth requirement, but does not detail side effects, permissions, or behavior on duplicate names.

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

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

The description is very short and to the point, conveying core purpose without extraneous words. However, it is slightly overly minimal, sacrificing parameter clarity for brevity.

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 creation tool with 3 parameters, no output schema, and no parameter descriptions, the description is insufficient. It fails to specify return value, error handling, or what constitutes a valid group, leaving significant gaps for an 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 0%, yet the description does not explain any of the three parameters (org, name, slug). It only mentions the resource name in passing. The agent lacks guidance on parameter meanings, formats, or constraints.

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

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

The description clearly states the action 'Create' and the resource 'shared group (reusable secret bag)' in an organization. The term 'Keyless' adds specificity. It distinguishes from sibling tools like delete_group, rename_group, and list_groups.

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 like compose_group or create_app. The description implies usage for creating groups to hold secrets, but does not provide when-not-to-use or prerequisites.

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

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

Description adds important behavioral details beyond annotations: 'Removes ciphertext — keyless — but irreversible' and 'Confirm intent before calling'. It clarifies the permanent, non-recoverable nature of the deletion and the lack of key-based recovery. Annotations already provide destructiveHint=true and idempotentHint=true, but the description enriches 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 concise sentences with clear front-loading. Every sentence provides value: action, scope, and warning. 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 destructive tool with no output schema and two parameters, the description covers the essential aspects: action, scope, irreversibility, and need for confirmation. However, it lacks parameter descriptions and does not specify behavior when the app does not exist. Still largely complete given the 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 0%, and the description does not explain the parameters 'app' and 'org'. Without any parameter descriptions, the agent must infer meaning from context, which is insufficient. The description should define what these parameters represent (e.g., application name, organization).

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 action (delete) and the resource (application and all its environments/secrets). It distinguishes from sibling tools like delete_branch, delete_env, delete_group, delete_secret by specifying the scope.

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

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

Description implies cautious usage with 'Confirm intent before calling' but does not explicitly state when to use this tool versus alternatives (e.g., delete_env for deleting only environments) or when not to use it (e.g., when selective deletion is needed).

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 destructiveHint and idempotentHint, but the description adds valuable context: the operation is keyless, removes ciphertext without reading, and the parent environment remains intact. 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 two sentences long and efficiently conveys essential behavioral traits. No unnecessary words, though it could include parameter hints.

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 3 parameters, no output schema, and annotations, the description explains key effects but omits parameter semantics and return behavior. It is moderately complete for a simple operation.

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

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

Schema description coverage is 0% and the description provides no information about the three parameters (app, org, branch). The agent cannot determine their meaning or required values from the description alone.

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 tears down an ephemeral branch config and its overrides, with specific details about being keyless and not affecting the parent environment. This distinguishes it from sibling delete tools like delete_app or delete_env.

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 the description implies usage for ephemeral branches, it does not provide explicit criteria for when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it.

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

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

Adds context beyond annotations: irreversible, removes ciphertext keyless. No contradiction with annotations; destructiveHint=true aligns.

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, detail, and warning. No redundant information, 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?

Covers purpose and behavior but misses parameter semantics. Without output schema, should explain what happens after deletion or return values.

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 0% and description does not explain parameters. Agent cannot infer that app and env are identifiers without additional 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 action (delete) and resource (application environment and its secrets). Distinguishes from siblings like delete_app, delete_branch, delete_group. Includes detail about ciphertext removal.

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?

Warns to confirm intent before calling, implying caution. Doesn't explicitly state when to use vs alternatives, but the destructive nature 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?

Description adds crucial context beyond annotations: 'Removes ciphertext — keyless — but irreversible.' Warnings about irreversibility and keyless removal are not in 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 clear sentences with no superfluous text: action stated then warning provided.

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 main effect and irreversibility but omits parameter details; no output schema needed.

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 0% description coverage; description does not explain the 'org' parameter, leaving the agent to infer its meaning.

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 'Delete a group and its environments/secrets', specifying the action and scope, distinguishing it from siblings like delete_env or delete_secret.

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?

Includes warning 'Confirm intent before calling' but does not explicitly state when to use this over alternatives like delete_env or delete_secret.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description adds value by noting that deletion is irreversible except by re-setting, and that no key is needed. This goes beyond annotation signals.

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, immediately states action and key behavioral notes. No wasted words. Front-loaded effectively.

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

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

Given 4 required parameters and no output schema, the description should at least mention what parameters are needed or what returns. It does neither, leaving the agent to rely on parameter names only. Lacks 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?

Schema description coverage is 0%, and the description provides no information about the 4 parameters (app, env, org, name). With no param guidance in either schema or description, the agent has to infer from names alone, which is insufficient.

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?

Clear verb-resource pairing: 'Delete a secret from an environment.' Adds specificity with 'Removes ciphertext — no key needed.' Does not explicitly differentiate from sibling restore_secret but the core action 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?

No explicit guidance on when to use or when not to use this tool versus alternatives like restore_secret. Mentions irreversibility but does not specify prerequisites or context for safe 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 declare readOnlyHint=true, indicating no destructive side effects. The description adds that it is a 'recipe,' implying informational output, but does not provide deeper behavioral details such as what happens if called multiple times or what exactly it returns.

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 and is reasonably concise. However, it could be slightly more structured, but it is not 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?

Given the tool has no parameters and is a simple read-only guide, the description covers the essential purpose and usage timing. However, it lacks details on what the output actually contains or how the recipe is presented, leaving some ambiguity.

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 in the input schema, and schema description coverage is 100% (trivial). The description does not add parameter information because none exist, which is acceptable.

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

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

The description states the tool is a 'recommended first-project recipe' that explains what to provision and encrypt locally. The verb is implicit (it's a guide), and it is somewhat vague but distinguishes from sibling tools which are more 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 explicitly says 'Call this before provisioning,' giving clear guidance on when to use this tool as a prerequisite. However, it does not mention alternatives or when not to use it.

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

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

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds value by revealing that the invitation is pending user sign-in, which is not in annotations. It also clarifies the admin authorization requirement. However, it does not disclose potential side effects like sending an email or duplicate behavior.

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 two clear clauses. It is front-loaded with the main action ('Invite someone to the organization by email') and contains no extraneous 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?

The description covers the core flow but misses key details: the 'org' parameter is optional but not explained, default role is not stated, and error cases or return values are absent. Given the lack of output schema and moderate complexity, the description is adequate but not 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 only 33% (role has a description). The tool description does not elaborate on the 'org' or 'email' parameters beyond the schema. It mentions 'by email' but adds little semantic value for the email parameter. For low coverage, the description should compensate but fails to do so.

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 invites someone by email, specifies it's admin-only, and explains the joining process. The verb 'invite' and resource 'member to organization' are distinct. Among siblings like revoke_invite, this tool's purpose is unmistakable.

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 mentions 'admin only', which provides a condition for use but does not explain when not to use it or alternatives (e.g., revoke_invite for cancellation). There is no explicit guidance on selecting this over other tools.

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

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

Annotations indicate destructiveHint=true and readOnlyHint=false. The description adds context about the behavior after disabling (existing ciphertexts remain decryptable locally), which is useful. No contradiction with annotations, but more detail on state changes or reversibility would improve 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, concise sentence that communicates the core function and a key behavioral note. It is front-loaded with the verb and avoids 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 has 2 parameters, no output schema, and annotations that partially cover behavior, the description lacks essential context. It does not explain the 'org' parameter, the meaning of 'Keyless', or prerequisites for usage. More detail is needed 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 has 2 parameters (org, keyId) with 0% schema description coverage. The description provides no additional meaning for these parameters, leaving the agent to rely solely on the schema.

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

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

The description clearly states the action ('Disable a managed KMS key') and explains the effect ('blocks new operations; existing ciphertexts stay decryptable locally by grantees'). It distinguishes from sibling tools like kms_list_keys and kms_revoke_grant, though the term 'Keyless' is somewhat ambiguous.

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 guidance on when to use or not use this tool, nor does it mention alternatives. 'Keyless' hints at a usage context but is not explicit.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds that key material is handled locally and only metadata is exposed, which is useful but not extensive. 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?

Single sentence that is concise, front-loads the action, and includes key context. 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?

While the description covers the core behavior and annotations provide safety and idempotency context, it completely omits the optional 'org' parameter. The tool has one parameter and no output schema, so the description should explain the parameter to be 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 has one optional string parameter 'org' with no description. The description provides zero information about this parameter, its purpose, or usage. With 0% schema coverage, the description should compensate but fails to do so.

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 managed KMS keys, specifies that it returns metadata only, and notes that key material is fetched and used locally. This distinguishes it from sibling tools like kms_disable_key and kms_revoke_grant, which modify keys.

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 vs alternatives. The context is implied from the action (read-only listing), but no when-not-to-use or alternative tools are mentioned.

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 destructive and idempotent behavior. Description adds the keyless trait, which is beyond annotations. No contradictions. However, lacks details on immediate effect, reversibility, or specific permissions required.

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 key trait. No redundant or extraneous information. Each sentence adds value.

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

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

Given a destructive action with 4 parameters (3 required) and no output schema, the description fails to document parameters, return behavior, or error scenarios. Agent would lack sufficient context to correctly invoke the tool without external knowledge.

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 0% and description provides no information about the parameters (org, keyId, principalId, principalType). The description only mentions 'principal' and 'key' generically, leaving the agent without any semantic guidance for the four 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?

Description clearly states the action: revoke a principal's grant on a managed KMS key. It specifies scope ('all versions') and a unique trait ('Keyless — the caller needs no key material'). Distinguishes from sibling tools like kms_disable_key and kms_list_keys.

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 implies usage when removing a grant, but does not explicitly state when to use or not use, nor does it mention alternatives or prerequisites beyond the parameters. No guidance on error conditions or when revocation is inappropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, fully covering the safety profile. The description adds no additional behavioral insights beyond stating that it lists apps, which is consistent with the annotations.

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

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

The description is very short (one sentence), which is concise but lacks necessary depth. It conveys the basic purpose but omits important details about parameters and context, so it is not optimally informative for its 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?

Given the simple tool (1 optional param, no output schema) and many sibling list tools, the description is too minimal. It does not mention the scope of 'applications' or whether the org parameter filters the list. The description is insufficient for an agent to select this tool over alternatives without additional 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?

The input schema has one optional parameter 'org' with no description. Schema description coverage is 0%, and the tool description does not explain what 'org' means or how it affects the results. The description adds no value beyond the schema.

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

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

The description explicitly states 'List applications in an organization,' providing a clear verb (list) and resource (applications in an organization). This distinguishes it from sibling tools like create_app, delete_app, and rename_app, which have different actions.

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 alternative list tools (e.g., list_envs, list_branches) or under what conditions. The description does not specify preconditions or typical scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: returns only metadata (names, parents, expiry) and never values, which is behavior not covered by annotations.

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

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

Two concise sentences: first states action and scope, second clarifies output content. No redundant or 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?

Given no output schema, description sufficiently explains return values and filter options. Could mention that 'org' is optional or clarify its usage, but overall adequate for a 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 0%; description clarifies that 'app' is the application and 'env' optionally filters to one environment. However, 'org' is not explained, leaving its role ambiguous.

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 lists ephemeral branch configs (per-PR/preview environments) for an application or a single environment, and specifies the returned fields (names, parents, expiry) with explicit exclusion of values. This distinguishes it from sibling tools like delete_branch or list_apps.

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 (listing branch configs without values) but does not explicitly state when to avoid this tool (e.g., when values are needed) or mention alternatives like secret retrieval tools.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that results are in 'precedence order', which is additional output behavior. No contradictions, but no further disclosure of auth needs or edge cases.

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, front-loaded with the verb and resource. It is concise but lacks coverage of usage and parameters, which reduces its overall communication efficiency.

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 (list operation, simple schema, no output schema, rich annotations), the description is nearly complete but fails to detail the return format or clarify 'precedence order'. With no output schema, the agent needs to infer what is returned (e.g., group names or objects).

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 0%, so the description must compensate for parameter meaning. However, it only implies that 'app' and 'env' identify the environment, without specifying format, constraints, or the optional 'org' parameter. This provides minimal added value over the schema's field names.

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 the groups composed into an application environment (precedence order)', specifying the verb (List), resource (groups composed into an application environment), and additional context (precedence order). It distinguishes from sibling tools like list_groups (lists all groups) and list_group_envs (lists environments for a group).

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 guidance on when to use this tool versus alternatives, no context for prerequisites or exclusions. It does not mention when not to use it or suggest 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying that only names and slugs are returned (never values), which is critical 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 clear sentence, front-loaded with the verb and resource, with no unnecessary words. Every part earns its place.

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

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

For a simple list tool with rich annotations, the description is mostly complete. It explains the output shape (names+slugs) despite no output schema. The only gap is lack of parameter details, but the tool is simple enough that this is minor.

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 0% for both parameters. The description only implies that 'app' is the application identifier by mentioning 'of an application', but provides no details on 'org' or parameter formats. This is insufficient for a 2-param tool with no 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 states a specific verb ('list'), resource ('environments'), scope ('of an application'), and explicitly limits the output to 'names + slugs only, never values'. This clearly distinguishes it from sibling tools like list_secrets or list_branches.

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 like list_secrets, list_branches, or list_apps. It does not provide any context about prerequisites or exclusions.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds domain context ('per-slug value sets') but no additional behavioral traits like pagination or response format.

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 with no filler, front-loaded with verb and resource. Every word adds value.

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

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

Despite good annotations and simple tool, the lack of parameter guidance makes the description incomplete for agent invocation. The description fails to explain how to use the required 'group' parameter.

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 parameter descriptions in schema (0% coverage) and description gives no details about 'org' or 'group' parameters, leaving their meaning and allowed values unspecified.

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 specific action (List) and resource (a group's environments) with clarifying parenthetical. Differentiates from sibling list tools like list_envs by specifying group-scoped retrieval.

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 like list_envs or list_env_groups. Implies group-scoped use but lacks explicit context or exclusions.

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

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

Annotations already convey readOnly, idempotent, and non-destructive nature. The description adds minimal behavioral context ('in an organization') beyond annotations. It does not disclose pagination, ordering, or response format.

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, clear sentence with no redundant information. However, it is too minimal and could benefit from additional structure without sacrificing conciseness.

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 output schema, the description should explain return values. It does not mention that it returns a list, nor does it cover pagination or optional parameter behavior. The tool is simple but important details are 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 has 0% description coverage for the single 'org' parameter. The description implies the parameter filters by organization but does not clarify its optionality, format, or behavior when omitted. This is insufficient compensation for low schema coverage.

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

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

The description clearly states the tool's action ('List'), resource ('shared groups'), and provides additional clarification ('reusable secret bags'). It effectively distinguishes from sibling tools like create_group, delete_group, 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?

No guidance is provided on when to use this tool versus alternatives (e.g., list_apps, list_envs). There is no mention of prerequisites, when not to use, or context for the optional org parameter.

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, openWorldHint, idempotentHint, destructiveHint) already cover safety and idempotency. 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 concise sentence, front-loaded with the key verb and resource, with 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?

No output schema is provided, and the description does not explain what the output contains or how the optional 'org' parameter affects results. Incomplete for a list tool.

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

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

Schema coverage is 0% and the description does not explain the 'org' parameter. It fails to add 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 'List pending invitations to join the organization' clearly specifies the action (list) and resource (pending invitations), and distinguishes from siblings like invite_member and revoke_invite.

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 pending invites, but lacks explicit guidance on when not to use it or alternatives. However, context with sibling tools helps.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that leases are temporary and that the list does not expose secret material, which is useful but not substantial beyond the annotations.

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

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

The description is a single front-loaded sentence that efficiently communicates the tool's core function without extraneous 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?

While the annotations provide safety context, the lack of parameter documentation leaves the agent uncertain about how to use the one parameter. No output schema means the agent cannot anticipate the response format.

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 'org' has no description in the schema (0% coverage) and the tool description does not explain its purpose, format, or effects.

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 temporary-access leases and specifies it is a ledger, not secret material. This distinguishes it from sibling tools like list_secrets and list_secret_versions.

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 such as list_lease_targets or revoke_lease. The agent has no context on when to prefer 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?

Description merely repeats 'List' which aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false), but does not add behavioral details like scope or limitations 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?

Single sentence, no redundancy. Could be slightly expanded to include parameter info, but avoids verbosity.

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

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

For a simple read-only list tool, the description covers the core action, but fails to explain the optional 'org' parameter. No output schema but acceptable for a 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 has one parameter 'org' with 0% coverage. Description does not explain what 'org' does, leaving the agent without guidance on its purpose or 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?

Description clearly states the verb 'List' and the resource 'registered temporary-access provisioning targets' with examples (Postgres, MySQL). This distinguishes it from sibling list tools like list_apps or list_envs.

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. No context about prerequisites or when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds that it lists public keys, which is useful context, but does not disclose additional behavioral traits beyond what annotations provide. No contradiction.

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

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

The description is a single sentence that is concise and front-loaded with the core action and context. Every word adds value, and there is 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?

Given the simplicity of the tool (one parameter, no output schema) and rich annotations, the description is adequate but not comprehensive. It does not mention pagination, public key format, or whether all members are always listed. It is minimally 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 input schema has one parameter 'org' with no description (0% coverage). The description mentions 'list organization members,' which implies the 'org' parameter refers to the organization, but it does not explicitly describe the parameter's format, allowed values, or behavior. The description fails to compensate for the lack of schema 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 lists organization members and their public keys, and provides a specific use case (used when granting access locally). This is a specific verb+resource combination, and it distinguishes itself from sibling tools like list_apps or invite_member.

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 mentions a use case ('used when granting access locally'), implying when the tool is useful, but does not explicitly state when not to use it or provide alternatives among siblings. It offers moderate 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that the list is scoped to organizations the caller can access, which provides minor 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?

The description is a single sentence that is concise, front-loaded, and contains no extraneous information. Every word serves a purpose.

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 rich annotations, the description is largely complete. However, without an output schema, it could hint at the structure of the response (e.g., 'returns a list of organization names or IDs'), but this 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?

There are zero parameters, and schema coverage is 100% trivially. The description does not need to add parameter details; it correctly conveys the tool's 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 'List' and resource 'organizations', and specifies the scope 'the caller can access'. It is distinct from sibling list tools by resource type, though it does not explicitly differentiate from similar tools like list_apps.

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 guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for related tasks.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical behavioral context: the tool never returns secret values and that value reading is handled by a separate tool. This fully informs the agent of the tool's limitations and design.

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 fluff. The first sentence states the core purpose, the second clarifies a critical limitation. 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?

The description explains the tool's purpose and limitation but omits output structure (return format, pagination) and does not explain the referenced setup_local_crypto tool. Given no output schema, more detail on the response would improve 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?

The input schema has 0% description coverage and the description provides no parameter details. It only vaguely references 'in an environment' without explaining app, env, or org parameters. The description adds no semantic value beyond the raw 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 tool lists secret names and versions, explicitly clarifies it never returns values, and distinguishes from value-reading tools like setup_local_crypto. This is a specific verb-resource combination with clear scope.

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

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

The description provides clear guidance on when to use this tool (listing) and when not to (for values), referencing setup_local_crypto. However, it does not cover other alternatives like list_secret_versions or delete_secret, leaving some usage ambiguity.

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 that only metadata is returned, never values, and that restore flags are shown. Annotations already show readOnlyHint, so description adds nuance about what metadata includes.

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 are front-loaded with purpose. No fluff, every sentence adds value.

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

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

Missing details on output format (fields returned) and pagination despite limit parameter. However, annotations and usage guidelines are strong. Adequate but not 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 has 20% description coverage (only limit has a default). Description does not explain app, env, name, or org parameters beyond context of listing a secret's history. Minimal compensation for low 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?

Clearly states it lists version history of a secret, including author, timestamp, and restore status. Explicitly distinguishes from value retrieval and pairs with restore_secret.

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 says to pair with restore_secret to undo a bad write, implying when to use it (before restoring). Also implies not to use when values are needed.

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 and destructiveHint. The description adds critical behavioral detail: it returns only metadata, never token strings. This is a significant addition 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?

One concise sentence that front-loads the core purpose. 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 simple listing tool with one optional parameter and no output schema, the description is sufficient but lacks parameter detail. Annotations cover safety, but completeness is moderate.

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 optional parameter 'org' has no description in the schema (0% coverage). The description mentions 'an organization' but does not explain the parameter, its purpose, or format. Minimal value added over 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?

Clearly states the verb 'list' and resource 'service tokens', and specifies it returns only metadata, never token strings. This distinguishes it from sibling listing tools like list_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?

No explicit guidance on when to use this tool versus alternatives, or when not to use it. The description only states what it does, leaving usage context implicit.

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, openWorldHint=true. Description explains it returns how to do operations locally, consistent with read-only nature. Adds context about server limitations.

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 purpose. 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 low complexity (1 param, no output schema), the description is complete enough. It explains when and how to use 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 covers the single parameter with description and example. Description adds no new information 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?

The description clearly states it provides local alternatives for operations the server cannot perform, with examples. It distinguishes itself from sibling tools that are concrete 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?

Explicitly says 'Use when a tool you expected is missing here.' Provides examples of operations. Does not explicitly state when not to use, but 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?

The description adds the constraint that the slug is immutable, which is beyond what annotations provide. However, it does not disclose other behavioral details such as error conditions, return values, or auth requirements beyond the 'Keyless' hint. Given that annotations already declare idempotentHint=true and destructiveHint=false, the description adds moderate value.

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, using a single sentence that front-loads the action 'Rename'. Every word serves a purpose, with no fluff 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 rename operation with three parameters and no output schema, the description is minimally adequate. It lacks details on return values, error handling, and the format of the app identifier. The missing 'org' parameter description also reduces 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?

The schema has 0% description coverage, so the description must compensate. It explains that 'app' is the application and 'name' is the new display name, but does not mention the 'org' parameter. This partial coverage leaves ambiguity, making it adequate but not thorough.

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 ('Rename') and the resource ('application's display name'), with a crucial constraint that the slug is immutable. This distinguishes it from sibling tools like 'rename_group', which operate on different resources.

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 is provided on when to use this tool versus alternatives or when not to use it. The description only explains what it does, leaving the agent to infer usage context from the siblings list.

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

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

Annotations provide some transparency (non-readOnly, non-destructive, idempotent). The description adds that the slug is immutable, which is valuable behavioral context. It does not describe side effects, but annotations cover the safety profile adequately.

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: a single sentence with a parenthetical. Every word is necessary. 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 simple rename operation, the description covers the basic purpose and a key constraint. However, it lacks parameter details and usage context, making it minimally viable but not 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?

Schema description coverage is 0%, so the description must compensate. Only 'name' is implicitly explained as the new display name; 'group' and 'org' are not described. The description does not add sufficient meaning beyond the parameter names.

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 'Rename a group's display name', specifying the verb and resource. It also notes the slug is immutable, which distinguishes it from other operations like create_group or delete_group. The purpose is unambiguous and 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?

No guidance is provided on when to use this tool vs alternatives like create_group or compose_group. There is no mention of prerequisites, context, or when not to use it.

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

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

Annotations indicate a write operation (readOnlyHint=false) that is not destructive (destructiveHint=false). The description adds valuable context: history is append-only, nothing is overwritten, and no decryption occurs. This explains the non-destructive nature and side-effect profile 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?

Three concise sentences: purpose, behavior, and keyless note. Front-loaded first sentence states purpose. No fluff or repetition. Every sentence adds value.

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

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

Explains core mechanism and key behavior, and references the companion tool. However, lacks information about the return value (no output schema), prerequisites (e.g., existence of versions), and error conditions. Adequate but with clear 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 description coverage is 0%, so the description must compensate. However, it only implicitly defines 'version' as the target version. The other parameters (app, env, name, org) are not explained, leaving the agent to infer their meaning from context. This is insufficient for the 5-parameter 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 tool's purpose: 'Roll a secret back to an earlier version.' It specifies the action (roll back), the resource (secret), and references the companion tool list_secret_versions, distinguishing it from others.

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 for when to use (rolling back a secret) and references list_secret_versions for finding versions. Explains append-only behavior and keyless operation, but lacks explicit when-not-to-use guidance or alternatives beyond the single reference.

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

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

Annotations already declare destructiveHint=true and the description 'Revoke' aligns. Beyond that, no additional behavioral traits are disclosed. The description does not add value beyond the annotations.

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

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

The description is a single sentence with no wasted words. It is front-loaded 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?

Given no output schema and zero parameter coverage in the description, the tool is incomplete. It does not explain the role of 'inviteId' or 'org', which are essential 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 description coverage is 0% and the description does not explain the two parameters ('org' and 'inviteId'). It fails to add meaning to what the schema provides, which is minimal.

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 'Revoke a pending organization invitation' uses a specific verb 'Revoke' and a clear resource 'pending organization invitation'. It distinguishes from sibling tools like 'invite_member' (send) and 'list_invites' (list).

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 pending invitations but provides no explicit when-to-use or when-not-to-use guidance. It lacks alternative suggestions or context.

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

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

Description says 'drops the credential immediately,' which aligns with destructiveHint: true, but adds little beyond annotations. It doesn't discuss irreversibility, required permissions, or side effects on associated resources.

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 efficiently conveys the core action. However, it omits parameter details, which would improve completeness without adding much 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?

Given no output schema and 0% parameter coverage, the description fails to explain what a lease is, how to obtain a leaseId, what org represents, or the result of revocation. Incomplete for a tool with two parameters.

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

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

Schema description coverage is 0%, and the description provides no information about the two parameters (org and leaseId). The agent cannot understand their purpose or format from the description.

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

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

The description clearly states the action (revoke), resource (temporary-access lease), and effect (drops credential immediately). It distinguishes from sibling tools like revoke_invite and revoke_token by specifying 'lease'.

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 vs alternatives, no prerequisites, and no mention of context such as needing an active lease or ownership. The agent must infer usage from the name alone.

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

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

The description adds meaningful context beyond annotations: it explains that revocation immediately stops future DEK fetches and advises key rotation if caching is possible. This complements the destructiveHint and idempotentHint annotations 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?

Two concise sentences, front-loaded with the main action and immediate effect. 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 tool's simplicity, annotations, and lack of output schema, the description covers purpose, effect, and a critical follow-up action. It is complete for an agent to understand when and how to use 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?

With 0% schema description coverage, the description partially compensates by referencing 'by id' for tokenId, but it does not explain the optional 'org' parameter or its purpose. The extra value over schema is limited.

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 ('Revoke'), the resource ('service token'), and the effect ('Future DEK fetches stop immediately'). It distinguishes from siblings like 'delete_token' or 'revoke_invite' by specifying it's a service token revocation.

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 guidance to 'Rotate the environment (locally) if the holder may have cached the key', which helps the agent decide follow-up actions. However, it does not explicitly contrast with alternatives or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, and the description adds that it provides a copy-paste .mcp.json, implying it outputs instructions. However, the phrase 'set and use secret values' could hint at mutation, but given readOnlyHint, it's likely instructional. No contradiction found.

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-loaded with the purpose, and every word adds value. 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?

With no parameters and no output schema, the description covers the tool's role (setup for secrets) and hints at the output (copy-paste .mcp.json). It is complete enough for a simple, read-only helper tool.

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

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

The tool has zero parameters and 100% schema coverage (empty schema). The description does not need to add param info, earning a baseline score of 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 sets up local crypto for secrets, with a specific verb ('run', 'set', 'use') and resource ('local crypto plane'), and distinguishes it from sibling tools like list_secrets or delete_secret by being a setup utility.

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 advises 'Call this the moment you need a secret's value', providing clear when-to-use context. It does not explicitly exclude scenarios or mention alternatives, but the context is sufficient for basic 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 provide basic hints (not read-only, open-world, not idempotent, not destructive). The description adds critical behavioral details: credential is bound to session, works without config change, clientSecret shown once for reconnect, and that it requires no human or browser. 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?

Five sentences, each providing essential information: purpose, binding behavior, credential saving instruction, and usage trigger. Front-loaded with the key action. No redundant or 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?

Despite no output schema, the description fully explains the tool's effect: creates workspace and credential, binds to session, instructs to save returned credentials for reconnect. Covers preconditions (tool says no credential) and postconditions. Sufficient for an AI agent to use 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 already provides good descriptions for all three parameters (100% coverage). The description adds warnings and context: orgName must be real (not placeholder), orgSlug must be URL-safe and not throwaway, and defaults for clientName. This adds meaningful guidance beyond schema.

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

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

The description clearly states the verb 'Create' and the resources 'seekrit workspace and your own machine credential'. It uniquely identifies the tool's purpose among siblings by emphasizing it is a one-call setup that binds credentials to the 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?

Explicitly states when to use: 'Call this if a tool says you have no credential.' Also provides context for credential binding and reconnection. Does not explicitly state when not to use, but the usage condition 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 indicate readOnlyHint=false and destructiveHint=false, but the description only adds 'Keyless', which is unclear. No behavioral details like permissions, side effects, or scope are disclosed. Annotations could be interpreted as contradictory (removing might be destructive), but description does not clarify.

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, very concise, but it omits critical information. It is appropriately short for what it says, but not effective.

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

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

Given 4 parameters, no output schema, and no parameter explanations, the description is severely incomplete. It fails to provide sufficient context 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 0%, meaning no parameter descriptions in schema. The description does not explain any of the four parameters (app, env, org, group). It adds no value beyond the raw schema, leaving the agent to guess their meanings.

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 'Remove' and the resource 'composed group' from an application environment. It distinguishes from sibling 'compose_group' by indicating the opposite action. The term 'Keyless' adds a slight contextual hint.

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 guidance on when to use this tool versus alternatives. It does not state prerequisites, context, or exclusions. The only sibling that relates is 'compose_group', but no comparison is made.

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 destructiveHint=false, so the agent knows it is safe. The description adds context about what the output contains (machine client and org), going 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: the first states purpose, the second gives usage guidance. No waste, every word earns its place.

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

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

Given no parameters, no output schema, and rich annotations, the description covers purpose and usage completely for this 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, so baseline is 4. The description does not need to add parameter 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 clearly states it shows the authenticated machine client and the org, which is a specific verb+resource. It distinguishes itself from sibling tools by indicating it is a discovery/introspection 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 phrase 'Call this first' explicitly tells the agent when to use it, providing clear context. No exclusions or alternatives are mentioned, but the guidance is sufficient for this simple tool.

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