seekrit — secrets for agents

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the trail is append-only, results are newest-first, and it covers all mutation types across multiple resources. This is meaningful additional 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?

Three purposeful sentences with no fluff: the first states the core function and scope, the second gives usage direction and a sibling alternative, and the third provides the return shape. Information is front-loaded and every sentence earns its place.

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

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

For a read-only tool with three optional parameters and no output schema, the description is complete: it explains ordering, scope, intended use, the key alternative, and the exact return record shape. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, and each parameter already has a clear description, including the org auto-detection behavior, limit range/default, and action filter guidance. The description adds only general context around ordering and scope, which does not materially extend what the schema already explains. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Read the organization's append-only audit trail') with clear scope ('every mutation across apps, environments, secrets, members, and tokens') and ordering ('most recent first'). It also explicitly names list_secret_versions as the narrower alternative, so an agent can immediately distinguish this tool from a key sibling.

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

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

It gives an explicit use case — answering 'what changed and who did it' — and an explicit exclusion: for one secret's history specifically, list_secret_versions is narrower and cheaper. This directly tells the agent when to choose this tool versus an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful behavioral context beyond that by explaining the return shape and the key semantic detail that `enforced: false` means plan limits are not currently applied. This helps the agent interpret results correctly.

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

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

Three sentences with no filler: the first states the tool's purpose, the second gives the key use case, and the third summarizes the return value and important semantics. Every sentence earns its place, and the most actionable guidance is front-loaded.

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

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

For a read-only, one-parameter tool with rich annotations and a self-explanatory return shape, the description is complete. It tells the agent what the tool returns, what the important flags mean, and when to call it. No output schema exists, but the description covers the essential output semantics sufficiently.

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 description itself adds no parameter-level meaning, but the input schema covers the single optional `org` parameter thoroughly, including default behavior and how to discover org slugs. With 100% schema description coverage, the baseline of 3 is appropriate; the description doesn't need to repeat it.

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

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

The description states a specific verb ('Show') and resource (the org's plan, entitlements, usage, and upgrade actions) with concrete scope. It is clearly distinct from sibling list tools like list_orgs or whoami, so an agent can identify what this tool is for without opening the schema.

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

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

The description gives an explicit trigger: 'Read this if a create action was refused with a plan limit.' It also explains what the tool will tell you in that situation, which is strong guidance for selecting this tool over alternatives. No exclusion cases are needed given the tool's unique purpose.

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

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

The annotations already mark idempotentHint=true, and the description adds meaning by explaining what idempotence means here ('composing an already-composed group just updates its position'). It also discloses 'No key material involved, so it runs here' and states the exact return shape. No contradiction with annotations exists.

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

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

The description is compact and front-loaded: the core action appears first, then safety, alternatives, and return value. Every sentence adds distinct value with no redundancy or fluff.

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

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

For a tool with three required parameters, rich schema descriptions, and relevant annotations, this description covers everything an agent needs: the operation's effect, idempotence semantics, how to undo, how to inspect ordering, why it can run locally, and the return value. Nothing essential is missing.

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

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

The input schema describes all five parameters with 100% coverage, including detailed semantics for position and org. The description does not add additional parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Compose a shared group into an application environment' and explains the effect ('environment resolves the group's secrets as well as its own'). It is clearly distinguished from sibling tools by naming uncompose_group and list_env_groups and their different purposes.

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

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

Explicitly routes to alternatives: 'Use uncompose_group to undo, and list_env_groups to see the current order.' It also notes that composing is safe to repeat, which directly guides when repeated calls are acceptable. This gives an agent clear decision context beyond just the action itself.

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 mutation (readOnlyHint=false) and non-idempotency. The description adds value beyond that by disclosing the return shape ({ id, orgId, name, slug, createdAt }), clarifying the app's role as owner of environments and secrets, and explaining the boundary with create_env and setup_local_crypto.

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

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

The description is compact and front-loaded with the core purpose. The only weakness is the third sentence's awkward phrasing ('Creating its environments does NOT: create_env mints...'), which is grammatically clunky but still conveys a crucial distinction.

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 lack of an output schema, the description compensates by listing the exact return object. It also provides enough setup context to prevent an agent from misusing this tool for environment creation. It could be slightly richer on the org parameter's behavior, but the schema already covers that.

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

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

Schema description coverage is 100%, and the schema already provides thorough explanations for org, name, and slug, including immutability of slug and the conditional behavior of org. The description adds no parameter-specific semantics beyond what the schema already documents, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Create an application — the container that will own environments and secrets.' It clearly distinguishes the app entity from related siblings like create_group and delete_app, and even clarifies that creating the app is not the same as creating its environments.

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

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

It explicitly explains when this step is appropriate: 'This step needs no key material, so it runs here.' It also warns against expecting environment creation here, pointing to create_env and setup_local_crypto as the correct tools for that separate concern.

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

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

Annotations already mark this as non-read-only, non-idempotent, and non-destructive. The description adds useful behavior beyond that: creating a group involves no key material, runs locally, and returns a specific new object shape { id, orgId, name, slug, createdAt }. It does not fully explain side effects or idempotency failure modes, but the annotations and creation semantics cover the essential safety profile.

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

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

The description is compact and well-ordered: it front-loads the core action, then explains the use case, the main alternative, the local-execution nuance, and the return shape. A few explanatory phrases are slightly ornate, but every sentence contributes either selection guidance or behavioral context. It earns 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?

For a 3-parameter tool with 100% schema description coverage and no output schema, the description supplies the missing return shape and creation context. An agent can call the tool with confidence: it knows what to pass from the schema, when to use this tool versus create_app, and what it will get back. The mention of create_group_env also orients the agent to related follow-up operations.

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?

All three parameters have descriptions in the schema at 100% coverage, so the schema carries almost the full burden. The description mentions name and slug only in the return object and adds no new parameter-level semantics, constraints, or examples. Baseline 3 is appropriate because the field descriptions already exist in the schema.

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

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

The description states a specific action and resource: 'Create a shared group' and defines what a shared group is (a reusable bag of secrets composed by many environments). It explicitly distinguishes the tool from create_app ('Use create_app instead for a deployable service') and clarifies the group's relationship to create_group_env. This is more than enough for an agent to understand what this tool creates.

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

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

The description gives explicit routing guidance: use create_app instead for a deployable service, while create_group is for shared secret bags. It also signals that no key material is involved, enabling local execution, and that group environments are minted by create_group_env, which points to the next step. Key alternatives are covered, so an agent can choose correctly.

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

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

The annotations already mark the tool as destructive, but the description goes further by detailing the irreversible nature, the lack of undo/export, the discarded ciphertext, and the widest-blast-radius warning. This adds meaningful behavioral context beyond what the structured 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?

Every sentence earns its place: the deletion effect, irreversibility, alternatives, human confirmation, and return shape are all covered in a compact description. The most critical scoping and safety information is front-loaded.

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

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

For a destructive tool with no output schema, the description supplies all essential context: what is deleted, the cascade to secrets, irreversibility, blast radius, safer alternatives, and what the response contains. There are no missing behavioral or safety details an agent needs before calling.

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

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

Schema description coverage is 100%, with both app and org parameters fully documented in the input schema. The description adds little parameter-specific detail beyond the schema, and the baseline of 3 applies because the schema already carries the parameter documentation burden.

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

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

The description states a specific verb and resource — deleting an application — and precisely scopes the blast radius to all environments and their secrets. It explicitly distinguishes itself from delete_env and rename_app, so an agent can tell which tool is which without inspecting schemas.

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

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

The description gives explicit when-to-use guidance: use this tool only for full application deletion, prefer delete_env for a single environment, and rename_app if the name is the only problem. It also instructs the agent to confirm intent with a human before calling, which is a clear and important usage condition.

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?

It discloses the destructive scope ('every value it overrode', 'parent environment is untouched') and warns that the operation is irreversible, going beyond the destructiveHint annotation. It also states the return shape '{ ok, branch }', though the cryptic create_branch/crypto sentence adds little.

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?

Most sentences are front-loaded and purposeful, but 'creating a branch mints a data key, so create_branch stays on the local crypto plane' is confusing and does not help callers invoke delete_branch. Not every sentence earns its place.

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

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

For a 3-parameter destructive tool with no output schema, it provides the return format, destruction scope, irreversibility, and the target use case. The unclear create_branch aside leaves a small completeness gap, but nothing essential for calling the tool is missing.

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

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

The input schema already covers all three parameters at 100%, so the baseline is 3. The description adds only a pointer to list_branches for the slug, which the schema already states, so no substantial new semantics are introduced.

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

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

The description opens with a specific verb and resource: 'Tear down an ephemeral branch config and every value it overrode.' It clearly distinguishes this from sibling delete_* tools by scoping it to branch config and stating the parent environment remains untouched.

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

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

It names the routine use case explicitly ('the routine cleanup when a PR merges') and tells the caller to find slugs with list_branches. It does not enumerate when-not-to-use cases or explicitly contrast with other delete tools, so it stops short of a 5.

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

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

The description goes well beyond the destructiveHint annotation by explaining exactly what is lost: ciphertext, the environment's data key, and all values in that environment. It clarifies that recreation requires setting every value again, which is critical behavioral context for an agent deciding whether to call this tool.

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

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

The description is appropriately concise and front-loaded with the core purpose before moving to consequences and alternatives. Every sentence contributes meaning, though the phrase 'local crypto plane' is slightly jargon-heavy and could be clearer for an unfamiliar agent.

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

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

For an irreversible, destructive tool with no output schema, the description covers the key consequences, the return shape, and the relevant alternatives. The schema handles parameter details, and the annotations handle the read-only and idempotency signals, so the description is complete for safe invocation.

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

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

The input schema already provides full documentation for all three parameters, including app and env with examples and org handling guidance. The description does not add much parameter-level detail, so the baseline score of 3 is appropriate given the 100% schema coverage.

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

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

The description clearly states the action (delete), the resource (one application environment), and the additional scope (the secrets it owns and the discarded ciphertext). It explicitly distinguishes itself from delete_app, which removes all environments, so an agent can tell this tool apart from its siblings.

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

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

The description explicitly says sibling environments and the application itself are untouched, and directs the agent to use delete_app when the intent is to remove all of them. It also instructs the agent to confirm intent before calling, which is useful guidance for a destructive operation.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses that the operation is irreversible, discards ciphertext, affects composed environments, and returns { ok, group }. This adds meaningful behavioral context about side effects and return shape that annotations alone do not provide, and it does not contradict any annotations.

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

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

The description is compact and well structured, front-loading the core destructive action, then the irreversibility, then the precautionary guidance, and finally the return value. Every sentence earns its place and there is 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?

Given the destructive nature of the tool, the description covers what is deleted, why it is dangerous, how to verify with list_env_groups, an alternative via uncompose_group, and the return shape. With annotations already covering safety hints and schema covering parameters, nothing critical is missing for an agent to decide and 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?

The input schema already provides 100% coverage with clear descriptions for both group and org parameters, so the description does not need to add parameter-level semantics. It mentions 'group' in context but adds little beyond the schema; the baseline of 3 is appropriate because the schema already carries the full burden.

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

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

The description clearly states the specific verb 'Delete' and the resource 'a shared group', and goes further to specify that it also removes the group's environments and their secrets. It is well distinguished from sibling tools like delete_app, delete_env, delete_secret, and uncompose_group, so an agent can immediately tell what resource is affected.

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

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

The description gives explicit pre-call guidance: check list_env_groups or use uncompose_group before deciding the group is unused. It also instructs the agent to confirm intent before calling, which is essential for a destructive operation. This clearly communicates when to use the tool and what safer alternatives exist.

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' destructiveHint, the description discloses irreversibility, that every version is discarded, that restoration is impossible, and that recreating requires setting the value again on the local crypto plane. It also states the exact return shape, { ok, name }, which is especially valuable since no output schema exists.

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

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

The description is compact yet information-dense, front-loading the core action and then layering essential warnings, usage guidance, and return format. Every sentence earns its place, and there is no redundant restatement of the tool name or schema.

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

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

For a destructive, irreversible operation, this description is complete: it explains side effects, irreversibility, the alternative tool, a confirmation warning, and return format. Combined with high schema coverage and relevant annotations, nothing critical is missing for an agent to invoke it safely and correctly.

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

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

Schema description coverage is 100%, and the schema already provides detailed meanings for app, env, org, and name. The description adds little parameter-specific value, but none is needed because the schema carries the full burden. This meets the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Delete a secret from an environment,' and immediately clarifies scope by saying 'discarding its ciphertext and every version.' It clearly distinguishes itself from siblings like restore_secret and delete_env by naming restore_secret explicitly and explaining the difference.

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

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

The description gives direct usage guidance: 'Prefer restore_secret to undo a bad write' and explains that restore_secret cannot recover a deleted secret. It also tells the agent to 'Confirm intent before calling,' making the when-to-use and when-not-to-use conditions 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 indicate readOnlyHint=true and the description reinforces this with 'Read' and 'returns a prose walkthrough.' It adds useful behavioral context beyond the annotation: no arguments are accepted, the output is prose, and calling it is non-destructive and low-cost. It does not contradict 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?

Two focused sentences: the first states what the tool does and returns, the second states when to call it and why. Every phrase earns its place, with no repetition of the tool name or title, and no filler.

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

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

For a no-argument, read-only informational tool, the description is complete: it states the content scope, output type, invocation timing, and value proposition. There is no output schema, but the description explicitly says the return is a prose walkthrough, so an agent knows what to expect. No critical information is missing.

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

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

The tool has zero parameters, so the schema carries no burden. The description explicitly states 'Takes no arguments,' confirming the empty input schema. This is the appropriate baseline for a parameterless tool, with no missing semantic guidance.

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

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

The description uses a specific verb ('Read') and names the exact resource ('the recommended first-project recipe'). It also explains what the tool covers: which steps run here and which need the local crypto plane, making its purpose concrete and distinguishable from the many provisioning and management siblings.

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

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

It explicitly instructs when to call the tool: 'Call this before provisioning anything.' It also gives the rationale—avoiding the cost of 'discovering the plane boundary one failed tool at a time'—which helps an agent decide to use it early in a workflow.

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

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

Beyond the annotations, the description discloses the admin-only requirement, the join-on-sign-in behavior, the pending state until first sign-in, and the key limitation that an invite alone conveys no ability to read values. It also states the exact pending object returned. No contradiction with the annotations exists; readOnlyfalse, destructivefalse, and idempotentfalse all align with an invitation-creating write that can be cancelled.

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

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

The description is compact and front-loaded with the essential action, then adds use-case guidance, the security boundary, and return shape. Every sentence contributes distinct information without filler or repetition.

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

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

For an invitation tool with no output schema, the description supplies the return shape, the sign-in semantics, the admin gate, and the relevant crypto-plane followup. Combined with rich input schema descriptions and annotations, this is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema itself already documents email, org, and role thoroughly. The description adds some behavioral context around the role and credentials, but it does not materially explain parameter syntax or formats beyond what the schema provides.

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

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

The description names the exact action, target, and access level: 'Invite a human to the organization by email (admin only).' It clearly distinguishes this from related tools by explaining that the invite results in a pending record that appears in list_invites, not list_vembers, and that revoke_invite cancels it. It also clarifies the capability boundary: the invite itself grants no ability to read values, which sets it apart from crypto/decryption 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?

It states a concrete scenario ('hand a project off to a person'), an admin-only precondition, and the necessary follow-up: grant decryption with grant_env on the LOCAL crypto plane. It also points the agent to revoke_invite for cancellation and to list_invites/list_vembers for pending versus active state, which is strong routing guidance.

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

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

Beyond the annotations, the description discloses irreversible-in-this-toolset behavior, the partial effect on existing ciphertext, and the return shape ('Returns the updated key, with `disabledAt` now set'). It does not contradict the destructiveHint annotation; instead, it clarifies exactly what the destructive impact is.

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

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

The description is compact but information-dense: main behavior, effect scope, reversibility caveat, sibling alternative, id lookup guidance, and return value are each covered in a single efficient paragraph. Every sentence contributes actionable guidance without redundancy.

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

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

For a destructive, single-parameter tool with no output schema, the description covers what happens before, during, and after the call. It explains the semantic effect, the limits of reversibility, the recommended sibling tool for a narrower operation, and what response to expect, so an agent has enough context to invoke it correctly.

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

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

Schema description coverage is 100%, and both `keyId` and `org` already have detailed schema descriptions, including the crucial warning that `name` is not accepted. The description reinforces the keyId source via kms_list_keys but does not add substantial new parameter information 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 opens with a specific verb and resource: 'Disable a managed KMS key,' and immediately defines the concrete effect on encrypt/sign operations. It distinguishes itself from kms_revoke_grant by contrasting whole-key disabling with cutting off one principal.

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

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

It explicitly names the alternative tool and the condition that selects it: 'Use kms_revoke_grant instead to cut off ONE principal while the key stays in service.' It also warns that no enable tool exists and directs the agent to kms_list_keys for finding the id, leaving no ambiguity about when or how 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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond those hints by explicitly stating 'Metadata only', clarifying that key material is fetched and used on the local crypto plane, and documenting the return shape with the semantic meaning of `disabledAt`. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place: what the tool lists, what it does not do, how to use the result, and the return shape. The core purpose is front-loaded, and the alternative-tool routing comes immediately after. No filler or redundant restatement.

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

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

For a list tool with one optional parameter and no output schema, the description is complete: it names the return fields, explains a key condition (`disabledAt` non-null), and gives cross-references to dependent tools. The annotations cover safety, and the schema covers parameters, so an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% for the single optional `org` parameter, and the schema already explains the omit-when-single-org behavior and the error fallback. The description does not need to repeat this; the baseline of 3 is appropriate because the schema carries the parameter semantics fully.

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

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

The description opens with a specific verb and resource: 'List the managed KMS keys the caller can see.' It further distinguishes itself from crypto-operation tools by stating that key material is fetched and used on the local crypto plane, not here. This clearly sets the scope as metadata-only listing and separates it from kms_encrypt/kms_decrypt/kms_sign.

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 tells the agent when to use this tool: to find a `keyId` for kms_disable_key or kms_revoke_grant. It also provides an exclusion by noting that encrypt/decrypt/sign operations live elsewhere, preventing misuse. This is strong, concrete routing guidance.

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

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

Beyond the destructiveHint annotation, the description states the exact blast radius: 'that user or service token can no longer use the key, while everyone else keeps working.' It also clarifies scope ('across all its versions') and the return shape, which is valuable for a destructive operation.

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

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

Four short sentences, each earning its place: action and effect, primary alternative, rationale, and return value. The information is front-loaded and there is no filler or repetition.

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

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

The combination of a rich schema, clear annotations, and a description covering effect, alternative, scope, and return value gives an agent everything needed to select and invoke the tool correctly. There is no output schema, but the description explicitly states the return object.

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

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

Schema description coverage is 100%, and the property descriptions are already detailed — they explain where to obtain keyId and principalId, and how org resolution works. The description itself does not add parameter-level detail, but that is acceptable because the schema carries the burden.

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

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

The description opens with a specific verb and resource: 'Revoke one principal's grant on a managed KMS key, across all its versions.' It also distinguishes itself from the main sibling by saying 'Use kms_disable_key instead to stop the key entirely,' so an agent can immediately tell what this tool does and what it does not do.

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

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

It explicitly names the key alternative and the condition for choosing it: stop the key entirely vs. revoke one principal's grant. The line 'Removing a grant needs no key material, which is why it runs here' also gives context about when this tool is the appropriate one 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by disclosing the exact return format and the relationship between apps, environments, and secrets, going beyond the structured annotations.

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

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

The description is compact and front-loaded: it states the purpose first, then adds the hierarchy context, the return type, and the next-step guidance. Every sentence earns its place, and there is no redundant repetition of the schema or annotations.

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

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

For a single-optional-parameter, read-only list tool with no output schema, the description is complete: it states what is listed, why, what is returned, and what to call next. The schema covers the one parameter's behavior, and annotations cover safety and idempotency, so nothing essential is missing.

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

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

Schema description coverage is 100% and the org parameter is already well-documented, including how omission behaves depending on credential scope. The tool description does not need to add much parameter detail, and the baseline of 3 applies when the schema carries the semantic weight.

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

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

The description states a specific verb and resource ('List the applications in an organization') and situates it in the hierarchy as the top-level container for environments and secrets. It also gives the exact return shape, making the tool's role unambiguous relative to siblings like list_envs and list_orgs.

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 to 'Start here when you know the org but not the app slug the other tools need' and directs the agent to 'use list_envs next to descend into one.' It provides clear context, though it does not spell out exclusions such as skipping this tool when the app slug is already known.

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 idempotentHint=true, so the read-only safety profile is covered. The description adds useful behavioral constraints beyond annotations: it never returns values, only metadata, and it specifies that `expiresAt` is null for branches without a TTL. This gives an agent confidence about exactly what to expect.

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 tight and every sentence earns its place: purpose, scope, data boundary, use cases, and return shape all appear without padding. The key qualification ('never values') is front-loaded, and the inline JSON example communicates the return structure compactly.

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?

There is no output schema, so the description carries the burden of explaining the return contract; it does so with an explicit row shape and the null-TTL rule. It also explains why an agent would call it (before delete_branch, spotting expired branches) and how to narrow scope, making it complete for a read-only 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 100%, so all three parameters (app, env, org) already have descriptive schema text. The description reinforces the `env` narrowing behavior and ties the returned slug to delete_branch, but it does not add substantial new parameter-level meaning beyond what the schema already 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 opens with a specific verb and resource: 'List ephemeral branch configs (per-PR / preview environments)', and scopes it to an application or branches forked from one environment. It also states the data boundary ('Names, parents, and expiry only — never values'), which makes it clear this is not a generic environment or secret listing 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 description gives explicit usage instructions: 'Use it before delete_branch to find a branch slug, or to spot branches that have already expired.' It also explains the narrowing behavior of the optional `env` parameter versus omitting it, providing enough context for an agent to decide when to call this tool.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important behavioral semantics: precedence order with higher position winning name clashes, and the returned list being ordered with the highest position last. No contradiction with annotations exists.

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, no filler. The core action and ordering are front-loaded, followed by concrete use cases and the return shape. Every sentence earns its place.

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

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

Even though there is no output schema, the description explicitly lists the returned fields and their ordering. It also covers the relationship to compose_group and list_group_envs, making the tool fully understandable for a read-only list operation with completely documented parameters.

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

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

Schema description coverage is 100%, and the schema already documents app, env, and org with examples and org fallback behavior. The description adds no parameter-level detail, but it does not need to; the schema already carries that burden.

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

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

The description opens with a specific verb and resource: 'List the shared groups composed INTO one application environment', and adds the defining precedence-order detail. It also distinguishes itself from sibling list_group_envs by explicitly naming it as the inverse direction, so an agent can tell the two apart without comparing schemas.

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

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

It provides two concrete use cases: explaining where a secret name actually comes from and choosing the next position for compose_group. It also names list_group_envs as the inverse direction, effectively telling the agent which sibling to consider instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond those: it returns names and slugs only, never values, and specifies the exact return fields. 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 compact and front-loaded: purpose first, then the key 'never values' caveat, then the return shape, then sibling disambiguation. Every sentence earns its place with no filler.

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

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

For a read-only list tool with no output schema, the description is complete: it states what is returned, the exact field shape, how to use the result, and how to route to related tools. Nothing essential for selecting or invoking it is missing.

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

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

Schema description coverage is 100%, so the schema already documents app and org thoroughly, including the org omission behavior. The description does not add much parameter-specific meaning, but with full schema coverage the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('environments an application owns'), with examples like production and staging. It explicitly differentiates itself from list_env_groups and list_group_envs, so an agent can distinguish it from siblings without opening their schemas.

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

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

It states when to use this tool: to find the env slug that list_secrets and delete/restore tools take. It also names the alternatives and what they do differently, giving clear when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context beyond that: the group's per-slug value separation and the exact returned Environment rows with groupId. It does not discuss pagination or open-world result size, but the openWorldHint annotation partially covers that.

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 tightly packed sentences: purpose, routing guidance, and return shape. No filler or redundant restatement of the tool name. Front-loads the core purpose before the alternatives.

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 appropriately specifies the return shape. Both parameters are fully covered by the schema, annotations cover safety and idempotence, and the description includes sibling routing. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds semantic value by explaining why groups matter ('a group holds a separate value set per slug, so its production differs from its staging'), which helps the agent reason about the group parameter even though the schema already names list_groups as the source.

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

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

States a specific verb and resource: 'List the environments belonging to one shared GROUP.' It also clearly differentiates from sibling tools by naming list_envs and list_env_groups, so an agent can select it correctly without opening other schemas.

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

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

Provides explicit when-to-use guidance: 'Use this when you already have a group and want its own environments; use list_envs for an application's, and list_env_groups to see which groups an application environment pulls from.' This directly names alternatives and the conditions that select this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavior beyond those annotations: it documents the exact return shape and notes that results are not paginated. It also explains the domain concept of a group as a reusable bag of secrets.

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?

Each sentence earns its place: the first states the action and defines the resource, the second gives the usage purpose and output/pagination details. No filler, and the most decision-relevant information is front-loaded.

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

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

For a simple read-only list tool with one optional parameter, rich annotations, and no output schema, the description supplies the missing return value shape and pagination behavior. It also ties the tool to downstream workflows. Nothing needed for correct invocation is missing.

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

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

The input schema has 100% coverage for the single optional org parameter, including detailed guidance about omitting it and the error behavior for multiple organizations. The description itself does not add parameter-level semantics beyond mentioning organization context, so the schema handles the burden and the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'List the shared groups in an organization.' It also defines what a group is and names the sibling tools that consume the group slug, so an agent can distinguish this from list_orgs, list_apps, and list_env_groups without opening schemas.

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

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

It gives an explicit use case: 'Use it to find the group slug compose_group and list_group_envs take.' This tells the agent when this tool is relevant. It does not explicitly state when not to use it or name competing list_* tools, but the concrete purpose makes the intended context clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond that: it clarifies the invitation lifecycle state ('sent but not yet accepted'), specifies the returned fields, and notes that accepted invitations transition to members. 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 compact and front-loaded with the core purpose, immediately followed by practical use cases and the return shape. Every sentence earns its place, and there is no redundant filler.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete: it states what is returned, how to use it, and how it relates to siblings. No missing information prevents correct selection or invocation.

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

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

Schema description coverage is 100%, and the org parameter is fully documented in the schema itself. The tool description does not add extra parameter semantics, but with full schema coverage, baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List invitations to the organization that have been sent but not yet accepted.' It clearly distinguishes this from list_members, since accepted invitations become members, and positions it relative to 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 states explicit use cases: 'confirm an invite_member call landed' and 'find an inviteId for revoke_invite.' It also routes the agent to list_members for accepted invitations, giving clear guidance on when to use this tool versus an alternative.

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 what annotations already declare, the description reveals a non-obvious behavior: the response never includes the credential itself. It also discloses the full return shape and the operational significance of lease status, which is valuable context an agent would not otherwise have.

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?

Each sentence has a distinct job: defining scope, stating an exclusion, giving usage guidance, and providing the return contract. The field list is long but justified because there is no output schema.

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

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

For a read-only, idempotent list tool with one fully documented optional parameter and no output schema, the description covers purpose, alternatives, invocation guidance, return fields, and an operational caveat. Nothing needed to invoke it correctly is missing.

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

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

The single optional org parameter is fully documented in the input schema, so the description does not need to add parameter-level detail. The description adds no new parameter semantics, making the baseline score of 3 appropriate.

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

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

The description names the exact action and object — listing issued temporary-access leases — and describes it as the ledger of who got a short-lived credential against which target and until when. It also explicitly distinguishes itself from list_lease_targets, which shows what can be leased, so an agent can tell them apart immediately.

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

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

It explicitly states when to call this tool: to find a leaseId for revoke_lease, and to check whether a lease has already expired before revoking it. It also names list_lease_targets as the relevant alternative for leasable targets, and adds the practical rule that only status: "active" leases are worth revoking.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: it clarifies that config is non-secret, what provider means, and what fields will appear in the result. It does not go into auth or rate limits, but with rich annotations the added context is sufficient.

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

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

The description is compact and front-loaded: first the resource and purpose, then usage guidance, then return shape. Every sentence earns its place, and there is no wasted or repetitive phrasing. The parenthetical clarifications are useful rather than distracting.

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

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

Even though there is no output schema, the description explicitly lists the returned fields and clarifies the meaning of provider and config. Combined with the fully documented optional org parameter and strong annotations, nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

The input schema has one optional org parameter with full description coverage, including behavior when omitted and when multiple orgs are reachable. The tool description itself adds no param-specific meaning, but the schema already documents the parameter thoroughly, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List the registered temporary-access targets.' It explains what those targets are (databases for minting short-lived credentials) and differentiates itself from list_leases by describing the returned object shape and the relationship to lease creation. This is unambiguous and immediately distinguishes it from sibling tools.

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

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

The description explicitly says to use this tool to see what can be leased before minting one, and directs users to list_leases for what has actually been issued. It also flags that create_pg_lease/create_mysql_lease run on the local crypto plane, which prevents the agent from expecting them as sibling MCP tools. This is clear when-to-use guidance with relevant alternatives.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds meaningful behavioral detail on top: the exact return shape and the critical edge case that publicKeyJwk is null for members who have not finished key setup, meaning they cannot be granted decryption. This is valuable beyond the annotations and compensates for the lack of an output schema.

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

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

The description is compact and front-loaded with the core action, then gives the practical reason to call it, then the return shape and null-key caveat. Every sentence adds information an agent needs, with no fluff or repetition of schema content.

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

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

For a simple, read-only listing tool, this is complete: purpose, invocation context, return shape, and an important behavioral edge case are all covered. The schema fully documents the only parameter, and annotations cover the safety profile, so nothing critical is missing.

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

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

The single optional org parameter is fully documented in the input schema, including slug-or-id semantics and multi-org error behavior. The description itself adds no parameter-level detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List organization members with their public keys') and goes beyond a generic list by tying the result to grant_env, a concrete downstream use. This clearly distinguishes it from sibling list tools like list_groups or list_invites.

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?

Gives a clear when-to-use signal: 'call this when handing a project off to a person.' It explains the purpose of the returned keys in the grant_env flow. It doesn't explicitly discuss exclusions or alternatives, but the intended context is unambiguous.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds useful context by stating the credential-based access scope and the exact return shape, which goes beyond what annotations provide without contradicting them.

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

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

The description is three short sentences with no wasted words. It front-loads the core purpose, then adds usage guidance and return format, every sentence earning 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 parameterless, read-only list tool with no output schema, the description is complete: it states purpose, usage context, alternative, and return structure. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

With zero parameters, the schema fully covers the input surface. The description adds no parameter details, but none are needed; the baseline for no-parameter tools is appropriately high.

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

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

The description clearly states the operation ('List the organizations') and the resource ('this credential can access'), making the tool's purpose immediately obvious. It also differentiates from whoami by specifying that list_orgs identifies the org slug rather than confirming the client identity.

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

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

It explicitly tells the agent when to use this tool: to find the org slug that every other tool takes. It also names the alternative, whoami, and the condition under which to prefer it, giving clear routing guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds a critical behavioral fact: the server cannot decrypt and therefore no tool here will ever return a secret value. It also discloses the exact return shape. This is valuable context an agent needs before selecting the tool.

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

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

Three sentences with no wasted words: scope, critical caveat, usage guidance, and return shape. The most important limitation is front-loaded immediately after the main action.

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

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

For a simple read-only listing tool, the description is complete: it explains what is returned, what is never returned, when to use it, and the alternative for reading values. The input schema fully documents parameters, and the output shape is explicitly stated despite the absence of an output schema.

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

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

Schema description coverage is 100%, with app, env, and org all explained in the schema. The description does not add extra parameter-level detail, but it does not need to because the schema already carries that burden. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'List the secret NAMES and versions in an environment.' It also clarifies what the tool does not do ('NEVER returns values'), which distinguishes it from value-reading operations like setup_local_crypto. The return shape further removes ambiguity.

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

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

The description gives an explicit use case: 'Use it to discover which names exist before referencing them.' It also names an alternative for reading values: 'run the local crypto plane (see setup_local_crypto)' and states a broad exclusion ('no tool here will ever return one'). It does not explicitly contrast with the sibling list_secret_versions, so it is not fully exhaustive.

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

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes further by adding the crucial 'metadata only, never values' boundary, explaining version-restore semantics, and revealing the newest-first ordering. This is meaningful behavioral context beyond what annotations alone provide, and there is no contradiction.

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

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

Three dense sentences carry all key information: action, scope, safety boundary, companion workflow, and return shape. There is no filler or repetition of schema content, and the most important distinguishing details are front-loaded.

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

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

There is no output schema, but the description supplies the exact return shape, field semantics, and ordering. Together with the rich parameter schema and the clearly named sibling tool restore_secret, this gives an agent everything needed to call the tool correctly and interpret the result.

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

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

The input schema has 100% coverage, with each parameter already described in detail, including examples and guidance for org, app, env, and limit. The description does not add parameter-level semantics; its value lies in explaining the output shape, which is relevant but not needed for parameter comprehension given the schema's completeness.

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

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

The description states a specific verb and resource: 'List one secret's version history' and clearly defines what is included (who wrote it, when, whether it was a restore) and what is excluded ('Metadata only — never values'). This distinguishes it from list_secrets and restore_secret, so an agent can tell them apart immediately.

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 pairs the tool with restore_secret in a concrete workflow: read the history here, then pass the version number to restore. This gives clear guidance on the primary use case. It does not enumerate explicit exclusions or alternatives beyond restore_secret, but the companion-tool pairing is enough for most selection decisions.

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 establish read-only, idempotent, non-destructive behavior, and the description adds meaningful context on top: tokens are shown once at creation on the local crypto plane and never retrievable here. It also explains null and non-null semantics for environmentId and revokedAt, which a caller needs to interpret results correctly.

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

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

Every sentence earns its place: definition, key behavioral warning, use cases, and return shape. The critical constraints are front-loaded, and the return format is specified compactly 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?

The tool has no output schema, so the description compensates by listing the exact returned fields and their semantics. The single parameter is fully documented in the schema, and the safety profile is covered by both annotations and description. Nothing needed to invoke or interpret this tool correctly is missing.

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

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

Schema coverage is 100% and the schema already explains the optional org param in detail, including omission behavior and how to handle multiple orgs. The description does not add parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description names a specific verb and resource ('List an organization's service tokens') and immediately distinguishes itself from related tools by clarifying it returns metadata only and never the token strings. It also explicitly connects to revoke_token, making its role among siblings 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?

States exactly when to call it: to find a tokenId for revoke_token or to audit active access. It also warns that token strings are not retrievable here, preventing misuse. No ambiguity about the intended use case.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds value by disclosing the return shape ({ operation, where, how }) and the behavior for unrecognized operations (a note explaining the plane boundary rather than an error), which goes beyond what the annotations alone provide.

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

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

The description is two sentences with no fluff. It front-loads the main purpose, then immediately provides the return shape and the key alternative. Every sentence earns its place.

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

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

For a single-parameter lookup tool with no output schema, the description is complete: it explains what the tool does, what it returns, what happens for unknown input, and when to use a sibling tool instead. No critical information for correct invocation is missing.

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

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

The schema already covers the single parameter completely, including a description, examples, and the unknown-name behavior. The description does not add meaningful parameter semantics beyond reinforcing the use case, so the baseline of 3 is appropriate given 100% schema coverage.

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

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

The description defines a specific verb–resource pair: 'look up how to perform one crypto-plane operation locally'. It also states the exact use case—when the expected tool is not on this server—and explicitly distinguishes this from setup_local_crypto, making the tool's unique role clear.

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

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

The description tells the agent when to use this tool ('the targeted answer for "the tool I expected is not on this server"') and names the alternative with its condition ('Use setup_local_crypto instead when you need the whole local setup rather than one command'). This gives explicit routing guidance with no need for inference.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: the slug is immutable, renaming breaks nothing, and it returns the updated object. It does not over-explain but provides enough to set expectations for a mutation.

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, each earning its place: the action, the crucial immutability caveat, the alternative when slug must change, and the return shape. No filler or redundancy, and the most important information is front-loaded.

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

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

The description covers the action, consequences, alternatives, and return type explicitly. Since there is no output schema, listing the returned fields is valuable and completes the picture. The annotation set already covers the safety profile, so no missing behavioral disclosure is apparent.

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

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

Schema description coverage is 100%, so the baseline is 3. The parameters app, org, and name are already well documented in the schema with examples. The description adds some context about the slug being immutable but does not need to repeat parameter details. It earns the baseline but no higher.

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

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

The description states a specific verb and resource ('Change an application's display name') and clearly distinguishes this tool from delete_app + create_app by explaining the slug is immutable. It is immediately clear that this tool is for renaming an app's display name, not for changing the slug or affecting other 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?

The description explicitly says when to use this tool vs the alternative: 'Use delete_app + create_app only if the slug itself must change.' It also reassures that renaming breaks nothing because other tools refer to the app by slug. This gives an agent a clear decision rule.

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 non-read-only, non-destructive, idempotent operation. The description adds valuable behavioral context by explaining that references from composed environments use the immutable slug, so renaming breaks nothing. It also discloses the return payload, going beyond annotation coverage.

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 with zero filler: the action comes first, then the important immutability guarantee, then the return shape. Every sentence earns its place and no information is repeated from the schema.

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 rename operation, the description covers the action, the key side-effect constraint (slug immutability and non-breaking behavior), and the return value even though no output schema exists. Combined with the fully described input schema, an agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with examples and guidance. The description does not need to add parameter-level detail and does not, which is acceptable under the baseline for full 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 opens with a specific verb and resource: 'Change a shared group's display name.' It explicitly distinguishes renaming from slug changes and, by naming 'group,' differentiates this from sibling tools like rename_app. The purpose is unambiguous and not a tautology.

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 clear usage context: use this tool when the display name must change while the slug stays stable. It also states an exclusion—the slug is immutable—so the agent knows not to attempt slug changes. It does not explicitly name alternatives like create_group or delete_group, but the context is sufficient.

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

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

Annotations only state readOnlyHint=false, idempotentHint=false, and destructiveHint=false, but the description goes further by explaining that history is append-only, nothing is overwritten, the ciphertext is replayed as a new version, and no decryption happens. This meaningfully enriches the tool's behavioral profile.

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

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

The description is compact and front-loaded with the core purpose, then adds the most important behavioral nuance, a prerequisite, and the return shape. Every sentence earns its place without unnecessary 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 tool of this complexity, the description covers the action, side effects, prerequisite, non-destructive nature, and return value. Even without an output schema, the explicit return shape makes the tool fully callable by 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 description coverage is 100%, so the schema already documents all parameters. The description reinforces that version comes from list_secret_versions and becomes a new head, but it does not add substantive parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: rolling a secret back to an earlier version, framed as 'the undo for a bad write.' It clearly distinguishes this from related operations like delete_secret by emphasizing append-only replay rather than overwrite or 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?

The description gives clear context for when to use the tool and explicitly instructs the agent to read list_secret_versions first to choose the version. It does not enumerate explicit when-not-to-use cases, but the prerequisite and behavioral framing provide solid usage guidance.

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

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

Annotations already mark the tool as destructive and non-read-only. The description adds the critical behavioral boundary that accepted invites cannot be revoked this way and states the expected return shape. This meaningfully supplements the annotations without contradicting them.

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

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

Three tight sentences: the action, the use case and limitation, the parameter source, and the return shape. Every sentence earns its place and the most important scoping constraint is front-loaded.

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

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

Given no output schema, the description still discloses the return value. The required parameter is sourced, the optional org behavior is in the schema, the accepted-invite edge case is handled, and destructive intent is already covered by annotations. Nothing material is missing 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 100%, so the schema already documents both org and inviteId clearly. The description reinforces the inviteId source ('from list_invites') but adds little beyond what the schema provides, which lands at the baseline for fully covered schemas.

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

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

The description opens with a specific verb ('Cancel') and a precise resource ('a pending organization invitation'), and distinguishes the action from related invite flows by noting it only applies before acceptance. This is immediately disambiguated from list_invites and 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?

It explicitly states when to use the tool ('an invite sent in error'), when it no longer applies ('once someone has accepted, they are a member'), and how to obtain the required parameter ('Find the id with list_invites'). This gives an agent clear decision-making 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?

The description goes well beyond the destructiveHint annotation by disclosing the immediate drop of the credential, the failure impact on existing holders, irreversibility, and the recovery path of minting a new lease. It also states the return shape. This is rich, non-obvious behavioral context that annotations alone do not convey.

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

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

The description is dense but every sentence earns its place: the action and consequence, irreversibility, prerequisite check, and return value. Information is front-loaded with the purpose and immediate effect, followed by practical guidance, with no filler.

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

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

For an irreversible destructive operation with no output schema, the description is complete: it explains the behavior, the consequence, the prerequisite check, the irreversibility, and the return format. An agent has enough information to invoke it correctly and anticipate the outcome.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds contextual guidance about checking list_leases first, but the leaseId parameter's provenance is already documented in the schema. No additional parameter semantics are introduced beyond what the schema provides.

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

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

The description states a specific verb ('Revoke'), a precise resource ('temporary-access lease'), and a concrete mechanism ('leased database credential is dropped at the target'). It clearly differentiates this from sibling revoke tools like revoke_token and revoke_invite by describing the unique resource and consequence.

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

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

The description gives explicit when-to-use context ('now instead of waiting for it to expire') and a when-not-to-use condition ('an already-expired lease needs no revoking'). It also directs the agent to list_leases first. However, it does not name alternative sibling tools for other revocation needs, so it misses the full 'alternatives' element.

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

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

Beyond the annotations, the description explains the immediate operational impact: 'Future key fetches by that token stop immediately, so any workload still using it loses access on its next read.' It also discloses the important limitation that revocation alone does not re-encrypt anything and warns about cached keys. This is rich, useful behavior context that annotations alone do not provide.

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

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

The description is concise, front-loaded with the core action, and every sentence contributes useful information: the effect, the consequence, the caching caveat, the lookup path, and the return shape. There is no wasted wording.

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

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

For a two-parameter tool with a destructive effect, the description covers the operation, immediate consequences, the important cached-key caveat, how to find the required id, and the return value. The annotations already signal destructiveness and non-read-only behavior, so nothing essential is missing for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only minor parameter guidance by telling the user to find the tokenId with list_tokens, but the schema already states that tokenId comes from list_tokens and is not the token string. The description does not need to compensate for missing schema documentation.

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

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

The description opens with a specific action and resource: 'Revoke a service token by id.' It clearly distinguishes this from sibling revoke tools by scoping to service tokens found via list_tokens, so an agent can tell it apart without checking schemas.

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

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

The description gives clear context: use revocation when you need a token to stop working immediately, and it points to list_tokens for obtaining the id. It also notes when an additional step is needed (rotating the environment if keys may be cached). It does not explicitly name sibling alternatives like kms_revoke_grant or revoke_invite, but the resource type makes the intended use fairly unambiguous.

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 and openWorldHint=false, and the description adds meaningful behavioral context: it returns prose plus config, reuses the session's credential, and explicitly warns that no tool will ever return a secret. This is valuable beyond the structured 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 focused sentences front-load the core purpose, then cover no-arg behavior, return value, and usage timing. Every sentence earns its place with no redundant filler.

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

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

The description is complete for a parameterless setup-and-info tool: it explains what is returned, when to call it, and how it differs from the relevant sibling. With no output schema present, the explicit return description is especially valuable.

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%, so the baseline is already high. The description further explicitly confirms 'Takes no arguments', removing any doubt about invocation requirements.

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: 'Get the exact commands' for running the local crypto plane, and names the specific components involved. It also distinguishes itself from the sibling local_tool_for, making the purpose 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?

It gives explicit timing guidance: 'Call this the moment you need to SET or READ a secret value'. It also names an alternative tool, local_tool_for, and states when that alternative is appropriate, giving clear routing direction.

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

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

Beyond the annotations, the description discloses critical behaviors: the credential is session-bound, the clientSecret is shown only once and cannot be retrieved later, and future reconnection depends on saving it. It also states the exact returned shape, giving the agent important expectations about side effects and persistence.

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

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

The description is dense but every sentence earns its place: purpose, session binding, return value, secret-retention warning, and when to call. It is front-loaded with the most important purpose and keeps operational guidance close behind.

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

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

Given the tool's complexity, 100% schema coverage, and the absence of an output schema, the description is complete. It explains the result shape, the one-time secret behavior, the session binding, and the invocation trigger. Nothing needed for correct use is missing.

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

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

Schema description coverage is 100%, and the schema already explains orgName, orgSlug, and clientName in detail. The description does not add parameter-level meaning, but it does not need to because the schema carries that burden. Baseline 3 is appropriate.

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

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

The description states a specific action and resource: create a workspace and a machine credential in one call. It also clearly differentiates this tool from the broader sibling set by positioning it as the no-human, no-browser bootstrap path that makes other tools work on the next call.

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

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

The description gives an explicit trigger condition: 'Call this if a tool says you have no credential.' It also explains that this is a one-time setup action and that the returned secret is the reconnection mechanism. It does not explicitly state when not to call it or name alternatives, but the guidance is clear enough for typical 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?

The description goes beyond the annotations by explaining the exact side effect: the group link is removed, secrets are untouched, and inherited names stop resolving. It also discloses idempotency ('Safe to repeat'), which aligns with and reinforces the idempotentHint annotation, and states the return value. No contradiction with annotations exists.

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

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

The description is compact and front-loaded: main action first, then side effects, then guidance, then repeatability and return type. Every sentence contributes meaningful information with no redundancy or filler.

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

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

Given the high schema coverage, rich annotations, and moderate complexity, the description is fully sufficient. It covers the operation, side effects, safety, idempotency, return value, and related tools, so an agent has everything needed to invoke it correctly.

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

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

The input schema already covers all four parameters with detailed descriptions and 100% coverage. The tool description does not need to add much parameter-level detail, and it does not. It provides useful context about the group being a 'composed group' but relies on the schema for parameter meanings, which is appropriate.

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

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

The description states a specific verb and resource: 'Remove a composed group from an application environment.' It immediately distinguishes the action from delete_group by clarifying that the group and its secrets remain untouched and only the link is dropped. This makes the tool's identity and scope 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 provides explicit preconditions and alternatives: 'Check list_env_groups first' and 'use delete_group to destroy the group itself.' It also warns when not to use it casually by noting that it can break workloads still reading inherited names. This is strong directional guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description goes beyond those by disclosing what the tool returns (the structured client/org object) and its role in credential validation. Since there is no output schema, this return-format disclosure carries important behavioral context for the agent.

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

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

Two tightly packed sentences with no filler. The most important usage instruction ('Call this first') is front-loaded, and the return format is summarized compactly. Every sentence earns its place and contributes to efficient agent decision-making.

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

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

For a zero-parameter, read-only introspection tool with no output schema, the description is fully self-sufficient: it states the purpose, when to call it, what it confirms, and exactly what it returns. There is no meaningful missing context that would prevent an agent from invoking 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 zero parameters, so there is nothing for the description to explain about parameters. Per the baseline for a 0-parameter tool, a 4 is appropriate; the description correctly avoids inventing parameter details and instead focuses on the tool's output and usage.

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

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

The description uses a specific verb ('Show') tied to a definite resource ('the authenticated machine client and the org it can access'). It is immediately distinguishable from sibling tools because it identifies the caller's identity/access context, and it even documents the return shape, leaving no ambiguity about what the tool does.

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

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

The explicit instruction 'Call this first' is a clear when-to-use directive that positions the tool as the expected entry point. The description also explains why to call it: it confirms the credential works and tells you which org slug to pass or that `org` can be omitted, giving practical guidance an agent can act on.

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